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PREFACE 


MANUAL OBJECTIVES 


The purpose of this manual is to provide all information necessary to 
interface directly with the I/O device drivers supplied as part of the 
RSX-11M/M-PLUS system. 


INTENDED AUDIENCE 


This manual is intended for use by experienced RSX-11M/M-PLUS 
programmers who want to take advantage of the time and/or space 
savings which result from direct use of the I/O drivers. Readers are 
expected to be familiar with the information contained in the 
RSX-11M/M-PLUS Executive Reference Manual, and to have some experience 
uSing the Task Builder and either MACRO-11 or FORTRAN programs and to 
be familiar with the manuals describing their use. 


STRUCTURE OF THE DOCUMENT 


Chapter 1 provides an overview of RSX-11M input/output operations. It 
is somewhat tutorial in its approach in introducing the reader to the 
use of logical unit numbers, directive parameter blocks, event flags, 
macro calls, etc. The discussions include the standard I/O functions 
common to a variety of devices, and summarizes standard error and 
status conditions relating to completion of I/O requests. . 


Chapters 2 through 23 describe the use of all device drivers supported 
by RSX-11M and/or RSX-11M-PLUS; refer to the preceding Summary Of 
Technical Changes to determine which drivers are supported in your 
operating system. Descriptions by chapter are as follows: 


Chapter Device Drivers 

2 Full-duplex terminal communications line 
interface 

3 Half-duplex terminal communications line 
interface 

4 Virtual terminal driver 

s) Disks 

6 DECtape 

7 DECtape II 

8 Magnetic tape 
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Chapter Device Drivers 
9 Cassette 
10 Line printers 
11 Card reader 
12 Message-oriented communications line 
interfaces 
13 PCL11 parallel communications link 


transmitter and receiver 


14 Analog-to-digital converters 

15 Universal digital controller 

16 Laboratory peripheral systems 

i? Paper tape reader/punch 

18 Industrial control subsystems 

19 The null device 

20 Graphics display terminals 

21 LPA11-K laboratory peripheral accelerator 
22 K-series laboratory peripherals 

23 UNIBUS switch 


Each of these chapters is structured in similar fashion and focuses on 
the following basic elements: 


Description of the device, including information on _ physical 
characteristics such as speed, capacity, access, and usage 


Summary of standard functions supported by the devices and 
descriptions of device-specific functions 


Discussion of special characters, carriage control codes, and 
functional characteristics, if relevant 


Summary of error and status conditions returned on acceptance 
or rejection of I/O requests 


Description of programming hints for users of the device under 
RSX-11M 
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Appendixes A through C provide quick reference material on I/0 
functions and status codes. These include the following: 


Appendix Contents 
A Summary of I/O functions by device 
B I/O function and status codes 
Cc QIO$ interface to Ancillary Control 
Processors 


ASSOCIATED DOCUMENTS 


Other manuals closely allied to the purposes of this document are 
described briefly in the RSX-11M/RSX-11S Information Directory and the 
RSX-1L1IM-PLUS Information Directory. Each Directory defines the 
intended readership of each manual in the RSX-11M/RSX-11S or 
RSX-11M-PLUS set and provides a brief synopsis of each manual's 
contents. 


CONVENTIONS USED IN THIS MANUAL 

There are a number of conventions and assumptions used in this manual 
to present syntax and program coding examples. These are described in 
the following list. 


1. Brackets ([]) in syntactic models enclose optional 
parameters. 


The following example illustrates this format: 
ASTXSS_ [err] 


2. Braces ({ ) in syntactic models indicate that one of the 
items must be selected, as in the following: 


DOM 
cat] {<snm, toon, Ldata, [42x] [4b] , [2am 
DOMW 


3. An ellipsis (...) in a syntactic model or coding example 
indicates that parameters have been omitted. As used in this 
manual, an ellipsis in a QIO macro call indicates omission of 
standard QIO parameters described in Section 1.5.1. This is 
illustrated below: 

QIOSC IO.RLV,...,<stadd,size> 


4. Consecutive commas in a coding example indicate null 
arguments. The following illustrates this usage: 


OLOSC- TOLATT 655.5 ;ASTOL 


5. Commas indicating null trailing optional arguments may be 
omitted, as in the following: 


QIosc I0O.KIL,9. 
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Certain parameters are required but ignored by RSX-11M or 
RSX-11M-PLUS; this is necessary to maintain compatibility 
with RSX-11D. For example, in the following, the priority 
specification (fourth parameter) is ignored: 


QIO$C IO.WLB,8.,EV,,10SB,ASTX,<IOBUF,NBUF> 


With the exception of MACRO-11 coding examples, all numbers 
in the text of this manual are assumed to be decimal; octal 
radix is explicitly declared as in the following: 


An illegal logical block number has been. specified 
for DECtape. The number exceeds 577 (1101 octal). 


In MACRO-11 coding examples, all numbers are assumed to be 
octal; decimal radix is explicitly designated by following 
the number with a decimal point, as in the following example: 


QIOSC I0.RDB,14.,,,10SB,,<IOBUF,80.> 


In FORTRAN subroutine models, parameters which begin with the 
letters i through n indicate integer variables, as in the 
following example: 


CALL DRS (ibuf,ilen,imode,irate,iefn,imask,isb, 
{nbuf],{istart],[istop]) 


In general, where hoth i and n prefixes are used in a call, 
the i form indicates the name of an array and the n form 
specifies the size of the array. 


All integer arrays and variables are assumed to occupy one 
storage word per variable (that is, INTEGER*2) and all real 
arrays and variables are assumed to occupy two storage words 
per variable (that is, REAL*4). 
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SUMMARY OF TECHNICAL CHANGES 


This update to the I/O Drivers Reference Manual contains changes’ and 
additions to document two operating systems: RSX-11M V4.1 and 
RSX-1LIM-PLUS V2.1. The following list contains a brief summary of 
technical changes for both operating systems: 


® Terminal driver support has been added for the following 
terminals: 


LQP02 
LA5O 
DHV11 


e Disk driver support has been added for the following new disk 
devices: 


UDA50/RA81 
UDAS0/RA60 
RC25 
RD51 
RX50 


@ Magnetic tape driver support has been added for the TU80 and 
TSVO5. 


e Line printer driver support has been added for the following 
printers: 


LNOL 
LP0O7 
LP26 
LP27 
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CHAPTER 1 


RSX-11M/M-PLUS INPUT/OUTPUT 


1.1 OVERVIEW OF RSX-11M 1/0 


The RSX-11M/M-PLUS Real-Time Executives support a wide variety of 
PDP-11 input and output devices, including disks, DECtapes, magnetic 
tapes, tape cassettes, line printers, card readers, and such 
laboratory and industrial devices as analog-to-digital converters, 
universal digital controllers, and laboratory peripheral systems. 
Drivers for these devices are supplied by Digital Equipment 
Corporation as part of the system software. This manual describes all 
of the device drivers supported by the system and the characteristics, 
functions, error conditions, and programming hints associated with 
each. Devices not described in this manual can be added to basic 
system configurations, but users must develop and maintain their own 
drivers for these devices. (See the RSX-11M Guide to Writing an I/0 
Driver, including Update No. 1, or the RSX-11M-PLUS Guide to Writing 
an I/O Driver, depending upon the system you are using.) a 


Input/output operations under RSX-11M are extremely flexible and are 
as device- and function-independent as possible. Programs issue I/0 
requests to logical units that have been previously associated with 
particular physical device units. Bach program or task is able to 
establish its own correspondence between physical device units and 
logical unit numbers (LUNS). I/0 requests are queued as issued; they 
are subsequently processed according to the relative priority of the 
tasks that issued them. I/0 requests (for appropriate devices) can be 
issued from tasks by means of either the File Control Services or 
Record Management Services, or can be interfaced directly to an I/O 
driver by means of the Queue I/O (QIO) system directive. 


All of the I/O services described in this manual are requested by the 
user in the form of QIO system directives. A function code included 
in the QIO directive indicates the particular input or output 
operation to be performed. I/0 functions can be used to request such 
operations as: 


e Attaching or detaching a physical device unit for a task's 
exclusive use 


e Reading or writing a logical or virtual block of data 
e Cancelling a task's I/O requests 
A wide variety of device-specific input/output operations (for 


example, reading DECtape in reverse, rewinding cassette tape) can also 
be specified with QIO directives. 
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1.2 PHYSICAL, LOGICAL, AND VIRTUAL I/0 


There are three possible modes in which an I/O transfer can take 
place: physical, logical, and virtual. 


Physical I/O concerns reading and writing data in the actual physical 
units accepted by the hardware (for example, sectors on a disk). For 
most devices, physical I/O is identical to logical I/O. For example, 
the RKO5 disk has sectors of 256 words, the same size as RSX-11M 
logical blocks for all disks. Thus, in this case, a logical block 
maps directly into a physical block. For other devices, the mapping 
is not one to one. The RF11 disk, for example, is word addressable; 
however, no physical I/0 may be done with the RF1ll. Data is always 
written in 256-word logical blocks. Another example is the RxX0l 
flexible disk. Data for the RX0l1 is recorded in physical sectors of 
64 words each. Therefore, logical blocks for the RX01 are made up of 
four physical sectors. 


Logical I/O concerns reading and writing data in blocks that are 
convenient for the operating system. In most cases, logical blocks 
map directly into physical blocks. For block-structured devices (for 
example, disks), logical blocks are numbered beginning at 0. For 
non-block-structured devices (for example, terminals), logical blocks 
are not addressable. 

Virtual I/O concerns reading and writing data to open files. In this 
case, the executive maps virtual blocks into logical blocks. For 
file-structured devices (disks or DECtapes), virtual blocks are _ the 
same size as logical blocks and are numbered starting from one (1) and 
are relative to the file rather than to the device. For 


non-file-structured devices, the mapping from virtual block to logical 
block is direct. 


1.3 RSX-11M DEVICES 
The devices listed below are supported by both RSX-11M and 
RSX-11M-PLUS, except as indicated. Drivers are supplied for each of 
these devices, and I/O operations for them are described in detail in 
subsequent chapters of this manual. 
l. A variety of terminals, including the following: 

e ASR/KSR-33 and ASR/KSR-35 Teletypes! 

e LA12 DECwriter 

e A100 DECwriter 

e £LA30 DECwriters (serial and parallel) 

e LA34/LA38 DECwriter IV 

e LA36 DECwriter II 

e £LA120 DECwriter III 

® LA180S DECprinter 


e LOQPO2 Letter-Quality Printer 


1. Teletype is a registered trademark of the Teletype Corporation. 
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These terminals are supported on the 
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LA50 Personal Printer 


VTOSB Alphanumeric Display Terminal 


VT50 Alphanumeric Display Terminal 


VT50H Alphanumeric Display Terminal 


VT52 Alphanumeric Display Terminal 


VT55 Graphics Display Terminal 


VT61 Alphanumeric Display Terminal 


VT100 


vVT101 


VT1LO0Z2 


VT105 


VT125 


VT131 


Alphanumeric 
Alphanumeric 
Alphanumeric 
Alphanumeric 
Alphanumeric 


Alphanumeric 


Display 
Display 
Display 
Display 
Display 


Display 


Terminal 
Terminal 
Terminal 
Terminal 
Terminal 


Terminal 


VT132 Alphanumeric Display Terminal 
RTO2 Data Entry Terminal 
RT02-C Badge Reader and Data Entry Terminal 


following asynchronous 


line interfaces: 


variety of disks, 


DJ11 Asynchronous Communication Line Interface Multiplexer 


DH11 and DH11-DM11-BB Asynchronous Communication Line 
Interface Multiplexer 

DHV11 Asynchronous Communications Line Interface 
Multiplexer 

DL11-A, DLI11-B, DL11-C, DL11-D, DL11-E and  DL11-Ww 
Asynchronous Communication Line Interfaces 

DLV11-E, DLV11-F Asynchronous Communication Line 
Interfaces 


DZ11 Asynchronous Communication Line Interface Multiplexer 
including the following: 

ML-11 Fast Electronic Mass Storage Device 

RF11/RS11 Fixed-Head Disk 

RSO3/RS04 Fixed-Head Disk 

UDA50/RA80/RA81 Fixed-Media Disk 

UDA50/RA60 Pack Disk 


RM80 Fixed-Media Disk 
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RPO7 Fixed-Media Disk 

RP11/RPO2 or RPO3 Pack Disks 

RMO2, RMO3, RMOS Pack Disk 

RPO4, RPOS, RPO6 Pack Disks 
RK11/RKO5 or RKOSF Cartridge Disks 
RL11/RLO1 or RLO2 Cartridge Disk 
RK611/RK06 or RKO7 Cartridge Disk 
RC25 Fixed-Media/Removable Cartridge Disk Subsystem 
RD51 Fixed-Media Disk 

RX50 Flexible Disk 

RX11/RX01 Flexible Disk 


RX211/RX02 Flexible Disk 


TC11/TU56 DECtape 


DL11/TU58 DECtape II 


A variety of magnetic tapes including the following: 


TU80 Magnetic Tape Subsystem 
TSVO5 Magnetic Tape Subsystem 
TS11 Magnetic Tape Subsystem 


TM11 Magnetic Tape Controller with TE10,TU10, or TS03 
Drive 


RH11/70 Controller with TM02/03 Formatter and TE16, TU16, 
or TU45 Drive 


RH11/70 Controller with TM03 Formatter and TU77 Drive 


RHL1/RH70 Controller with TM78 Formatter and TU78 Drive 


TA11 Tape Cassette 


A variety of line printers: 


LP1li Controller with LP14, LPOl1, LP0O2, LPO4, LPOS, LP0O6, 
LPO7, LP26, LP27 Line Printers 


LS11 Controller and Line Printer 
LV11l Controller with LVOl Line Printer 
LA180 Controller and Line Printer 


LNOL Laser Printer 


CR1l1 Card Reader 
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Synchronous and asynchronous line interfaces: 


DA11-B Asynchronous Communication Line Interface 


support only) 


DL11-E Asynchronous Communication Line Interface 


Support only) 


DLV11-E Asynchronous Communication Line Interface 


DMC11 Synchronous Communication 


DP11 Synchronous Communication 
support only) 


DQ11 Synchronous Communication 
support only) 


DU11 Synchronous Communication 
support only) 


DUP11 Synchronous Communication 


Line Interface 


Line Interface 


Line Interface 


Line Interface 


Line Interface 


(RSX-11) 


(RSX-11M 


(RSX-11M 


(RSX-11M 


(RSX-11M 
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10. Two analog-to-digital converters: 

@e AFC11 Analog-to-Digital Converter (RSX-11M support only) 

e ADO1-D Analog-to-Digital Converter (RSX-11M support only) 
11. UDC11 Universal Digital Controller (RSX-11M support only) 
12. Laboratory peripheral systems: 

e AR11 Laboratory Peripheral System (RSX-11M support only) 


e LPS11 Laboratory Peripheral System (RSX-11M Support only) 


- 
ive) 
© 


Paper tape devices: 

@ PCll Paper Tape Reader/Punch 

e PR11 Paper Tape Reader 

14. Industrial control subsystems: 

e “ICS/ICR Local and Remote Subsystems (RSX-11M support only) 


e DSS/DRS Digital Input and Output Subsystems (RSX-11M 
support only) 


15. The "Null Device," a software construct that facilitates 
eliminating unwanted output 


16. Two graphics subsystems: 
e VT1l1l Graphics Display System (RSX-11M support only) 
e VS60 Graphics Display System (RSX-11M support only) 
17. Laboratory Peripheral Accelerator: 
e LPA11-K 
18. K-series laboratory peripherals: 
e AA11-K Digital-to-Analog Converter and Display 
@e AD11-K Analog-to-Digital Converter 
e AM11-K Multiple-Gain Multiplexer 
e DR11-K Digital I/O Interface 
e kKW11-K Programmable Real-Time Clock 


19. PCL11 Parallel Communications Link (RSX-1l1M-PLUS support 
only) 


20. DTO7 (RSX-11M-PLUS support only) UNIBUS Switch 


21. Virtual Terminals (RSX-11M-PLUS support only) 


1.4 LOGICAL UNITS 


This section describes the construction of the logical unit table and 
the use of logical unit numbers. 
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1.4.1 Logical Unit Number 


A logical unit number, or LUN, is a number associated with a physical 
device unit during RSX-11M/M-PLUS I/O operations. For example, LUN 1 
might be associated with one of the terminals in the system, LUNS 2, 
3, 4, and 5 with DECtape drives, and LUNs 6, 7, and 8 with disk units. 
The association is a dynamic one; each task running in the system can 
establish its own correspondence between LUNs and physical device 
units, and can change any LUN/physical-device-unit association at 
almost any time. The flexibility of this association contributes 
heavily to system device independence, 


A logical unit number is simply a short name used to represent a 
logical-unit/physical-device-unit association. Once the association 
has been made, the LUN provides a direct and efficient mapping to the 
physical device unit, and eliminates the necessity to search the 
device tables whenever the system encounters a reference to a physical 
device unit. 


The user should remember that, although a  LUN/physical-device-unit 
association can be changed at any time, reassignment of a LUN at run 
time causes pending I/O requests for the previous LUN assignment to be 
cancelled. It is the user's responsibility to verify that all 
outstanding I/0 requests for a LUN have been serviced before that LUN 
is associated with another physical device unit. 


1.4.2 Logical Unit Table 


There is one Logical Unit Table (LUT) for each task running in a 
system. This table is a variable-length block contained in the task 
header. Each LUT contains sufficient 2-word entries for the number of 
logical units specified by the user at task-build time by the "UNITS=" 
option. 


Each entry or slot contains a pointer to the physical device unit 
currently associated with that LUN. Whenever a user issues an I/0 
request, the system matches the appropriate physical device unit to 
the LUN specified in the call by indexing into the LUT by the number 
supplied as the LUN. Thus, if the call specifies 6 as the LUN, the 
system accesses the sixth 2-word entry in the LUT and associates the 
I/O request with the physical device unit to which the entry points. 
The number of LUN assignments valid for a task ranges from 0 to 255, 
but cannot be greater than the number of LUNs specified at task-build 
time. 


Figure 1-1 illustrates a typical Logical Unit Table. 


NUMBER OF LUNS 


UCB 
UCB 
UCB 


UCB 


ZK-004-81 


Figure 1-1 Logical Unit Table 


1=6 
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Word 1 of each active (assigned) 2-word entry in the logical unit 
table points to the Unit Control Block (UCB) of the physical device 
unit with which the LUN is associated. This linkage may be indirect; 
that is, the user may force redirection of references from one unit to 
another unit with the MCR command REDIRECT. Word 2 of each entry is 
reserved for mountable devices. 


1.4.3 Changing LUN Assignments 


Logical unit numbers have no significance until they are associated 
with a physical device unit by means of one of the methods described 
below: 


1. At task-build time, the user can specify an ASG_ keyword 
option, which associates a physical device unit with a 
logical unit number referenced in the task being built. 


2. The user or system operator can issue a REASSIGN command to 
MCR; this command reassigns a LUN to another physical device 
unit and thus’ changes the LUN-physical device unit 
correspondence. Note that this reassignment has no effect on 
the in-core image of a task. 


3. At run time, a task can dynamically change a LUN assignment 
by issuing the Assign LUN system directive, which changes the 
association of a LUN with a physical device unit during task 
execution. 


1.5 ISSUING AN I/O REQUEST 


User tasks perform I/O in the RSX-11M/M-PLUS system by submitting 
requests for I/0 service in the form of QIO or QIO And Wait system 
directives. See the RSX-11M/M-PLUS Executive Reference Manual for a 
complete description of system directives. 


In RSX-11M/M-PLUS, as in most multiprogramming systems, tasks do not 
normally access physical device units directly. Instead, they utilize 
input/output services provided by the Executive, since it can 
effectively multiplex the use of physical device units over many 
users. The Executive routes I/O requests to the appropriate device 
driver and queues them according to the priority of the requesting 
task. I/O operations proceed concurrently with other activities in an 
RSX-11M/M-PLUS system. 


Before a request is queued, it must pass a battery of acceptance tests 
administered by the Executive. If the request fails, it is rejected; 
this rejection is signalled by the setting of the C-bit when the 
statement following the QIO is’ executed. It is good programming 
practice to check for directive rejection by following the QIO 
directive with a BCS instruction. 


After an I/O request has been queued, the system does not wait for the 
operation to complete. If at any time the user task that issued the 
QIO request cannot proceed until the I/O operation has completed, it 
should specify an event flag (see Sections 1.5.1 and 1.5.2) in the QIO 
request and should issue a Waitfor system directive specifying the 
same event flag at the point where synchronization must occur. The 
task then waits for completion of I/O by waiting for the specified 
event flag to be set. 
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The QIOW directive, QIO And Wait, is a more economical way to achieve 
this synchronization. QIOW automatically waits until I/O has 
completed before returning control to the task. Thus, the additional 
Waitfor directive is not necessary. 


Each QI0O or QIOW directive must supply sufficient information to 
identify and queue the I/O request. The user may also want to include 
locations to receive error or status codes and to specify the address 
of an asynchronous system trap service routine. Certain types of I/0 
operations require the specification of device-dependent information 
as well. Typical QIO parameters are the following: 


e 1/0 function to be performed 


e Logical unit number associated with the physical device unit 
to be accessed 


e Optional event flag number for synchronizing I/O completion 
processing (required for QIOW) 


e Optional address of the I/O status block to which information 
indicating successful or unsuccessful completion is returned 


e Optional address of an asynchronous system trap service 
routine to be entered on completion of the I/O request 


e Optional device- and function-dependent parameters specifying 
such items as the starting address of a data buffer, the size 
of the buffer, and a block number 


A set of system macros that facilitate the issuing of QIO directives 
is supplied with the RSX-11M/M-PLUS”~ system. These macros, which 
reside in the System Macro Library (LB:[1,1]RSXMAC.SML), must be made 
available to the source program by means of the MACRO-11 Assembler 
directive .MCALL. The function of .MCALL is described in Section 
1a Pade Several of the first six parameters in the QIO directive are 
optional, but space for these parameters must be reserved. 


During expansion of a QIO macro, a value of 0 is defaulted for all 


null (omitted) parameters. Inclusion of the device- and 
function-dependent parameters depends on the physical device unit and 
function specified. Tf the user wanted to specify only an I/0 


function code, a LUN, and an address for an asynchronous system trap 
service routine, the following might be issued: 


QITOSC IO.ATT,6,,,,ASTOX 


IO.ATT 


The I/O function code for attach. 


The LUN. 


ASTOX 


The AST address. 
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rree 


Null arguments for the event flag number, the request priority, 
and the address of the I/O status block. 


No additional device- or function-dependent parameters are required 
for an attach function. The C form of the QIOS macro is used here and 
in most of the examples included in Chapter 1. Section 1.7 describes 
the three legal forms of the macro. 


For convenience, any comma may be omitted if no parameters appear. to 
the: F1Ighe “o£ Ane. The command above could therefore be issued as 
follows, if the asynchronous system trap was not desired: 


QIOosc IO.ATT,6 


All extra commas have been dropped. If, however, a parameter appears 
to the right of any place-holding comma, that comma must be retained. 


1.5.1  QI10 Macro Format 


The arguments for a specific QIO macro call may be different for each 
I/O device accessed and for each I/O function requested. The general 
format of the call is, however, common to all devices and is as 
follows: 


or1osc. fne,lun, (efn}; [pri], [isb], last] [,<pl;p2,...,;p6>] 


where brackets ([]) enclose optional or function-dependent parameters. 
If function-dependent parameters <pl,...,p6> are required, these 
parameters must be enclosed within angle brackets (<>). The following 
Paragraphs Summarize the use of each QIO parameter. Section 1.7 
discusses different forms of the QIOS macro itself. 


The fnce parameter is a symbolic name representing the I/O function to 
be performed. This name is of the form 


IO.XxXxX 


XXX 


Identifies the particular I/O operation. 


For example, a QIO request to attach the physical device unit 
associated with a LUN specifies the function code 


IO.ATT 


A QIO request to cancel (or kill) all I/O requests for a specified LUN 
begins in the following way: 


OQTOSC I0.KIL,.«. 


The fne parameter specified in the QIO request is stored internally as 
a function code in the high-order byte and modifier bits in the 
low-order byte of a single word. The function code is in the range 0 
through 31 and is a binary value supplied by the system to match the 
symbolic name specified in the QIO request. The correspondence 
between global symbolic names and function codes is defined in the 
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system object module library, which is automatically searched by the 
Task Builder. Local symbolic definitions may also be obtained by the 
FILIOS and SPCIOS macros, which reside in the System Macro Library and 
are summarized in Appendix A. Several similar functions may have 
identical function codes, and may be distinguished only by their 
modifier bits. For example, the DECtape read logical forward and read 
logical reverse functions have the same function code. Only the 
modifier bits for these two operations are stored differently. 


The lun parameter represents the logical unit number (LUN) of the 
associated physical device unit to be accessed by the I/O request. 
The association between the physical device unit and the LUN is 
specific to the task that issues the I/O request, and the LUN 
reference is usually device independent. An attach request to the 
physical device unit associated with LUN 14 begins in the following 
way: 


QIOSC IO.ATT,14.,... 


Because each task has its own LUT in which the physical device 
unit-LUN correspondences are established, the legality of a LUN 
parameter is specific to the task that includes this parameter in a 
QIO request. In general, the LUN must be in the following range: 


0 <LUN <length of task's LUT (if nonzero) 


The number of LUNs specified in the LUT of a particular task cannot 
exceed 255. 


The efn parameter is a number representing the event flag to be 
associated with the I/O operation. It may optionally be included ina 
QIO or QIO And Wait request. The specified event flag is cleared when 
the I/O request is queued and is set when the I/O operation has 
completed. If the task has issued the QIO And Wait directive, 
execution is automatically suspended until the I/O completes. If a 
QIO directive has been issued (with no Waitfor directive), then task 
execution proceeds in parallel with the I/O. When the task continues 
to execute, it may test the event flag whenever it chooses by using 
the Read All Event Flags system directive (if group global event flags 
are not being used) or the Read Extended Flags system directive (for 
all event flags, including group-global event flags). If the user 
specifies an event flag number, this number must be in the range 1 
through 96. If an event flag specification is not desired, efn can be 
omitted or can be supplied with a value of 0. Event flags 1 through 
32 are local (specific to the issuing task); event flags 33 through 
64 are global (shared by all tasks in the system). Event flags 65 
through 96 are group-global event flags (shared by all tasks in the 
Same user group). Flags 25 through 32 and 57 through 64 are reserved 
for use by system software. Within these bounds, the user can specify 
event flags as desired to synchronize I/0 completion and task 
execution. Section 1.5.2 provides a more detailed explanation of 
event flags and significant events. 


NOTE 


If an event flag is not specified, the 
Executive treats the directive as if it 
were a simple QIO request. 
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The optional pri parameter is supplied only to make RSX-11M/M-PLUS QIO 
requests compatible with RSX-11D. An RSX-11M I/O request 
automatically assumes the priority of the requesting task. Thus, it 
is recommended that a value of 0 (or a null) be used for this 
parameter. 


The optional isb parameter identifies the address of the I/O status 
block (I/0 status double-word) associated with the I/O request. This 
block is a 2-word array in which a code representing the final status 
of the I/0 request is returned on completion of the operation. This 
code is a binary value that corresponds to a symbolic name of the form 
IS.xxx (for successful returns) or IE.xxx (for error returns). The 
binary error code is returned to the low-order byte of the first word 
of the status’ block. It can be tested symbolically, by name. For 
example, the symbolic status IE.BAD is returned if a bad parameter is 
encountered. The following illustrates the examination of the I/0 
status block, IOST, to determine if a bad parameter has been detected: 


QIOSC IO.ATT,14.,2,,10ST 


BCS DIRERR 
WTSESC 2 

CMPB #IS.SUC,IOST 
BNE ERROR 


The correspondence between global symbolic names and I/0 completion 
codes is defined in the system object module library, which is 
automatically searched by TKB. Local symbolic definitions, which are 
Summarized in Appendix B, may also be obtained by the IOERRS macro, 
which resides in the System Macro Library. 


Certain device-dependent information is returned to the high-order 
byte of the first word of isb on completion of the I/O operation. If 
a read or write operation is successful, the second word is also 
Significant. For example, in the case of ae read function ona 
terminal, the number of bytes typed before a carriage return is 
returned in the second word of isb. If a magtape unit is the device 
and a write function is specified, this number represents the number 
of bytes actually transferred. The status block can be omitted from a 
QIO request if the user does not intend to test for successful 
completion of the request. 


The optional ast parameter specifies the address of a service routine 
to be entered when an asynchronous system trap occurs. Section 1.5.3 
discusses the use of asynchronous system traps, and Section 2.2.5 of 
the RSX-11M/M-PLUS Executive Reference Manual describes traps in 
detail. If the user wants to interrupt his task to execute special 
code on completion of an I/O request, an asynchronous system trap 
routine can be specified in the QIO request. When the specified I/0 
operation completes, control branches to this routine at the software 
priority of the requesting task. The asynchronous code beginning at 
address ast is then executed, much as an interrupt service routine 
would be. If the user does not want to perform asynchronous 
processing, the ast parameter can be omitted or a value of 0 specified 
in the QIO macro call. 


The additional QIO parameters, <pl,p2,...,p6>, are dependent on_ the 
particular function and device specified in the I/O request. Typical 
parameters may include I/0 buffer address, I/0 buffer length, and_ so 
EOL this Between zero and six parameters can be included, depending on 
the particular I/O function. Rules for including these parameters and 
legal values are described in subsequent chapters of this manual. 
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1.5.2 Significant Events 


"Significant event" is a term used in real-time systems to indicate a 
change in system status. In RSX-11M/M-PLUS, a significant event is 
declared when an I/O operation completes. This signals the system 
that a-change in status has occurred and indicates that the Executive 
should review the eligibility of all tasks in the system to determine 
which task should run next. The use of Significant events helps 
cooperating tasks in a real-time system to communicate with each 
other, and thus’ allows these tasks to control their own sequence of 
execution dynamically. 


Significant events are normally set by system directives, either 
directly or indirectly, by completion of a specified function. Event 
flags associated with tasks may be used to indicate which significant 
event has occurred. Of the 96 event flags available in 
RSX-11M/M-PLUS, the flags numbered 1 through 32 are local to an 
individual task and are set or reset only as a result of that task's 
operation. The event flags numbered 33 through 64 are common to all 
tasks. Flags 25 through 32 and 57 through 64 are reserved for system 
software use. The event flags numbered 65 through 96 are group-global 
event flags, which are common to all tasks running under the same user 
group. 


An example of the use of significant events follows. A task issues a 
QIO directive with an efn parameter specified. A Waitfor directive 
follows the QIO and specifies as an argument the same event flag 
number. The event flag is cleared when the I/O request ©“. queued by 
the Executive, and the task is blocked when it executes the Waitfor 
directive until the event flag is set and a significant event is 
declared at the completion of the I/O request. The task resumes when 
the appropriate event flag is set, and execution resumes at the 
instruction following the Waitfor directive. During the time that the 
task is blocked, other tasks have a chance to run, thus increasing 
throughput in the system. 


1.5.3 System Traps 


System traps are used to interrupt task execution and to cause a 
transfer of control to another memory location for special processing. 
Traps are handled by the Executive and are relevant only to the’ task 
in which they occur. To use a system trap, a task must contain a trap 
service routine, which is automatically entered when the trap occurs. 


There are two types of system traps: Synchronous and asynchronous. 
Both are used to handle error or event conditions, but the two traps 
differ in their relation to the task that is running when they are 
detected. Synchronous traps signal error conditions within the 
executing task. If the same instruction sequence were repeated, the 
Same synchronous trap would occur at the Same place in the task. 
Asynchronous traps Signal the completion of an external event such as 
an I/O operation. An asynchronous system trap (AST) usually occurs as 
the result of initiating or completing an external event rather than a 
program condition. 


The Executive queues ASTs in a first-in-first-out queue for each task 
and monitors all asynchronous’ service routine operations. Because 
asynchronous traps may be the end result of I/O-related activity, they 
cannot be controlled directly by the task that receives’ them. 
However, the task may, under certain circumstances, block recognition 
of ASTs to prevent simultaneous access to a critical data region. 
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When access to the critical data region has been completed, the queued 
ASTS may again be honored. The DSARSS (Disable AST Recognition) and 
ENARSS (Enable AST Recognition) system directives provide the 
mechanism for accomplishing this. An example of an asynchronous trap 
condition is the completion of an I/O request. The timing of such an 
operation clearly cannot be predicted by the requesting task. If an 
AST service routine is not specified in an I/O request, a trap does 
not occur and normal task execution continues. 


Asynchronous system trapS associated with I/0 requests enable the 
requesting task to be truly event driven. The AST Service routine 
contained in the initiating task is executed as soon as_ possible, 
consistent with the task's priority. Using the AST routine to service 
I1/O-related events provides a response time that is considerably 
better than a polling mechanism, and provides for better overlap 
processing than the simple QIO and Waitfor sequence. Asynchronous 
system traps also provide an ideal mechanism for use in multiple 
buffering of I/O operations. 


All ASTs are inserted in a first-in-first-out queue on ae per. task 
basis as they occur (that is, the event that they are to Signal has 
expired). They are effected one at a time whenever the task does not 
have ASTs disabled and is not already in the process of executing an 
AST service routine. The process of effecting an AST involves storing 
certain information on the task's stack, including the task's Waitfor 
mask word and address, the Directive Status Word (DSW), the PS, the PC 
and any trap dependent parameters. The task's general-purpose 
registers RO-R5 are not saved, and thus it is the responsibility of 
the AST service routine to save and restore the registers it uses. 
After an AST is processed, the trap-dependent parameters (if any) must 
be removed from the task's stack and an AST Service Exit directive 
executed. The ASTXSS macro described in Section 1.7.6 of this manual 
is used to issue the AST Service Exit directive. On AST service exit, 
control is returned to another queued AST, to the executing task, or 
to another task that has been waiting to run. The RSX-11M/M-PLUS 
Executive Reference Manual describes in detail the purpose of AST 
service routines and all system directives used to handle them. 


1.6 DIRECTIVE PARAMETER BLOCKS 


A Directive Parameter Block (DPB) is a fixed-length area of contiguous 
memory that contains the arguments specified in a system directive 
macro call. The DPB for a QIO directive has a length of 12 words. It 
is generated as the result of expanding a QIO macro call. The first 
byte of the DPB contains the directive identification code (DIC) 
-- always 1 for QIO. The second byte contains the size of the DPB in 
words -- always 12 for RSX-11M/M-PLUS. During assembly of a user task 
containing QIO requests, the MACRO-11 Assembler generates a DPB for 
each I/O request specified in a QIO macro call. At run time, the 
Executive uses the arguments stored in each DPB to create, for each 
request, an I/O packet in system dynamic’ storage. The packet is 
entered by priority into a queue of I/O requests for the specified 
physical device unit. This queue is created and maintained by the 
Executive and is ordered by the priority of the tasks that issued the 
requests. The I/O drivers examine their respective queues for the I/0 
request with the highest priority capable of being executed. This 
request is dequeued (removed from the queue) and the I/O operation is 
performed. The process is then repeated until the queue is emptied of 
all requests. 
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After the I/O request has been completed, the Executive declares a 
Significant event and may set an event flag, cause a branch to an 
asynchronous system trap service routine, and/or return the I/0 
status, depending on the arguments specified in the original QIO macro 
call. Figure 1-2 illustrates the layout of a sample DPB. 


BYTE 


DIC FOR QIO 
DIRECTIVE 


MODIFIERS I/O FUNCTION 


2 Vreseneo74 wn | LOGICAL UNIT NUMBER 
3 PRIORITY __ EVENT FLAG NUMBER 


4 ADDRESS OF I/O 
STATUS BLOCK 


ADDRESS OF 
ASYNCHRONOUS TRAP 
SERVICE ROUTINE 


5 AST 


6 DEVICE- 


° DEPENDENT 


° PARAMETERS 
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Figure 1-2 QI0O Directive Parameter Block 


1.7 I/O-RELATED MACROS 


Several system macros are supplied with the RSX-11M/M-PLUS system _ to 
issue and return information about I/O requests. These macros reside 
in the System Macro Library and must be made available during assembly 
by the MACRO-11 assembler directive .MCALL. 


Also supplied are FORTRAN-callable subroutines that perform the same 
functions as the system macros. See the RSX-11M/M-PLUS Executive 
Reference Manual for details. 


There are three distinct forms of most of the system directive macros 
discussed in this section. The following list summarizes the forms of 
QIOS, but the characteristics of each form also apply to QIOWS, ALUNS, 
GLUNS, and other system directive macros described below. 


1. QIOS generates a directive parameter block for the I/0 
request at assembly time, but does not provide the 
instructions necessary to execute the request. This form of 
the request is actually executed using the DIRS macro. It is 
useful if the DPB is to be used in Several different places 
in the task and/or modified or referenced by the task at run 
time. 
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2. QIOSS generates a directive parameter block for the I/0 
request on the stack, and also generates code to execute the 
request. This is a useful form for reentrant, shareable code 
Since the DPB is generated dynamically at execution time. 


3. QIO$SC generates a directive parameter block for the I/O 
request at assembly time, and also generates code to execute 
the request. The DPB is generated in a separate program 
section called SDPBSS. This approach incurs little system 
overhead and is useful when an I/O request is executed from 
only one place in the program. 


Parameters for both the QIOS and QIOSC forms of the macro must be 
valid expressions to be used in assembler data-generating directives 
such as .WORD and .BYTE. Parameters for the QIOSS form must be valid 
source operand address expressions to be used in assembler 
instructions such as MOV and MOVB. The following example references 
the same parameters in the three distinct forms of the macro call. 


QIOS IO.RLB,6,2,,,AST01,<RDBUF,80.> 
QIOSC IO.RLB,6,2,,,AST01,<RDBUF,80.> 
QIOSs #IO.RLB,#6,#2,,,#ASTO1,<#RDBUF, #80.> 


Only the QIOSS form of the macro produces the DPB dynamically. The 
other two forms generate the DPB at assembly time. The 
characteristics and use of these different forms are described in 
greater detail in the RSX-11M/M-PLUS Executive Reference Manual. 


The following Executive directives and assembler macros are described 
in this section: 


1. QI0S, which is used to request an I/O operation and supply 
parameters for that request 


2. QOIOWS, which is equivalent to QIOS followed by WTSES 


3. DIRS, which specifies the address of a directive parameter 
block as its argument, and generates code to execute the 
directive 


4. .MCALL, which is used to make available from the System Macro 
Library all macros referenced during task assembly 


5. ALUNS, which is used to associate a logical unit number with 
a phySical device unit at run time 


6. GLUNS, which requests that the information about a physical 
device unit associated with a specified LUN be returned to a 
user-Specified buffer 


7.  ASTXSS, which is used to terminate execution Of an 
asynchronous system trap (AST) service routine 


8. WTSES, which instructs the system to block execution of the 
issuing task until a specified event flag is set 
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1.7.1 The QIO$ Macro: Issuing an I/O Request 


As described in Section 1.7, there are three distinct forms of the 
QIOS macro. QIOSS generates a DPB for the I/O request on the stack, 
and also generates code to execute the request. QIOSC generates a DPB 
and code, but the DPB is generated in a separate program section. 
QIOS generates only the DPB for the I/O request. This form of the 
macro call is used in conjunction with DIRS (see Section 1.7.2) to 
execute an I/O request. In the following example, the DIRS macro 
actually generates the code to execute the QIO$ directive. It 
provides no QIO parameters of its own, but references the QIO 
directive parameter block at address QIOREF by supplying this label as 
an argument. 


QIOREF: QIOS IO.RLB,6,2,,,ASTO1,<BUFFER,80.> 

° ; CREATE QIO DPB 
READI: DIRS #OIOREF ; ISSUE I/O REQUEST 
READ2: DIRS #OIOREF ; ISSUE I/O REQUEST 


1.7.2 The QIOWS Macro: Issuing an I/O Request and Waiting for an 
Event Flag 


The QIOWS macro is equivalent to a QIOS followed by a WTSES. It is 
more economical to issue a QIO And Wait request than to use the two 


separate macros. An event flag (efn parameter) must be specified with 
QIOWwsS. 


1.7.3 The DIRS Macro: Executing a Directive 


The DIRS (execute directive) macro has been implemented to allow a 
task to reference a previously defined DPB. It is issued in the form: 


DIRS {addr][,err] 


addr 
The address of a directive parameter block to be used in _ the 
directive. If addr is not included, the DPB itself or the 
address of the DPB is assumed to already be on the stack. This 
parameter must be a valid source operand for a MOV instruction 
generated by the DIRS macro. 

err 


An optional argument which specifies the address of an error 
routine to which control branches if the directive is rejected. 
The branch occurs by means of a JSR PC, err if the C-bit is set, 
indicating rejection of the QIO directive. 
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1.7.4 The .MCALL Directive: Retrieving System Macros 


-MCALL is a MACRO-11 Assembler directive that retrieves macros’ from 
the System Macro Library (LB:[1,1]RSXMAC.SML) for use during assembly. 
It must be included in every user task invoking system macros. .MCALL 
is usually placed at the beginning of a user-task source module and 
specifies, as arguments in the call, all system macros that must be 
made available from the library. 


The following example illustrates the use of this directive: 


-MCALL QIO$,QIOSS,DIRS,WTSESS ; MAKE MACROS AVAILABLE 


ATTACH: QIOSS #IO.ATT,#6,,,10SB,#ASTO2 ; ATTACH DEVICE 


QIOREF: QIOS IO.RLB,6,,,I10SB,ASTO1,... 3; CREATE ONLY QIO DPB 


READ1: DIRS #QIOREF,DIRERR 


ISSUE I/O REQUEST 


=e 


As many macro references as can fit on a line can be included in a 
Single .MCALL directive. There is no limit to the number of .MCALL 
directives that can be specified. 


1.7.5 The ALUNS$ Macro: Assigning a LUN 


The Assign LUN macro is used to associate a logical unit number with a 
physical device unit at run time. All three forms of the macro call 
may be used. Assign LUN does not request I/O for the physical device 
unit, nor does it attach the unit for exclusive use by the issuing 
task. It simply establishes a LUN-physical device unit relationship, 
so that when the task requests I/O for that particular LUN, the 
associated physical device unit is referenced. The macro is issued 
from a MACRO-11 program in the following way: 


ALUNS lun,dev,unt 


lun 
The logical unit number to be associated with the specified 
physical device unit. 

dev 
The device name of the physical device or a logical device name 
assigned to a physical device (see MCR ASN command). 

unt 


The unit number of that device specified above. 
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For example, to associate LUN 10 with terminal unit 2, the following 
macro call could be issued by the task: 


ALUNSC 10.,TT,2 


A unit number of O represents unit 0 for multiunit devices such as 
disk, DECtape, or terminals; it indicates the single available unit 


for devices without multiple units, such as card readers and line 
printers, 


Logical devices are SYSGEN options that allow the user to assign 
logical names to physical devices by means of the MCR command ASN. 
See the RSX-11M/M-PLUS MCR Operations Manual for a full description. 


The example included below illustrates the use of the three forms of 
the ALUNS macro. 


DATA DEFINITIONS 


me te Ne 


ASSIGN: ALUNS LO. ;TT,2 7 GENERATE DPB 


EXECUTABLE SECTION 


me ™e NO 


DIRS$ #ASSIGN 


EXECUTE DIRECTIVE 


=e 


ALUNSC 10.,TT,2 


GENERATE DPB IN SEPARATE PROGRAM 
SECTION, THEN GENERATE CODE TO 
EXECUTE THE DIRECTIVE 


me Oe NO 


ALUNSS #10.,#"TI,#0 GENERATE DPB ON STACK, THEN 


EXECUTE DIRECTIVE 


ue ™€O 


1.7.5.1 Physical Device Names - The following list contains physical 
device names, listed alphabetically, that may be included as dev 
parameters: 


Name Device 


AD ADO1-D Analog-to-Digital Converter (not supported in 
RSX-11M-PLUS systems) 


AF AFC11 Analog-to-Digital Converter (not supported in 
RSX-11M-PLUS systems) 


AR AR11 Laboratory Peripheral System (not supported in 
RSX-11M-PLUS systems) 


Name 


BS 


CD 


CP 


CR 


CT 


DB 


DD 


DF 


DK 


DL 


DM 


DP 


DR 


DS 


DT 


DU 


DX 


DY 


EM 


GR 


ic 


Is 


LA 


LP 


LS 
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Device 
DTO3/DT07 UNIBUS Switch (supported in RSX-11M-PLUS 
systems only) 


CD11 Card Reader 


Central Processor Unit (CPU) in a multiprocessor 
system (supported in RSX-11M-PLUS systems only) 


CR11/CM11 Card Reader 

TAL1/TU60 Tape Cassette 

RPO4, RPOS, RPO6 Pack Disk 

TU58 DECtape II 

RF1IiI/RSiil Fixed-Head Disk 

RK11/RK05 Cartridge Disk 

RL11/RLO1L/RLO2 Cartridge Disk 

RK611/RK06 and RK711/RKO7 Cartridge Disk 
RP11/RPO02/RPO03 Pack Disk 


RMO2/RM03/RMO5 Pack Disk and RM80/RP07 Fixed-Media 
Disk 


RSO3 and RSO4 Fixed-Head Disks 

TC11/TU56 DECtape 

RA80/RA81 Fixed-Media Disk, RA60 Pack Disk, RC25 Disk 
Subsystem, RD51 Fixed-Media Disk, and RX50 Flexible 
Disk 

RX11/RX01 Flexible Disk 

RX211/RX02 Flexible Disk 


ML-11 Fast Electronic Mass Storage Device 


VT11/VS60 Graphics Systems (not supported in 
RSX-1L1M-PLUS systems) 


ICS/ICR Industrial Control Local and Remote Subsystems 
(not supported in RSX-11M-PLUS systems) 


DSS/DRS Digital Input and Output Subsystems (not 
supported in RSX-11M-PLUS systems) 


LPA11-K Laboratory Peripheral Accelerator 


LA1L80/LP11/LS11/LV11 Line Printers and LNO1l Laser 
Printer 


LPS11 Laboratory Peripheral System (not supported in 
RSX-11M-PLUS systems) 
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Name 


MF 
MM 
MS 
MT 
NL 
PP 
PR 


LR 


TT 


LT 


UD 


XB 


XL 


XM 


XP 


XQ 


XU 


XW 


YH 


YL 


YZ 


ZA-ZZ 
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Device 


TU78 Magnetic Tape 
TUL6/TE16/TU45/TU77/TMO2/TMO3 Magnetic Tape 
TS11, TU80, or TSVO5 Magnetic Tape 
TM11/TU1O/TU11 or TSO03 Magnetic Tape 

The Null Device 

PCll Paper Tape Punch 

PCll or PR11 Paper Tape Reader 


PCL11-A/PCL11-B Receiver Port (supported in 
RSX-11M-PLUS systems only) 


Terminals (regardless of interface) 


PCL11-A/PCL11-B Transmitter Port (supported in 
RSX-11M-PLUS systems only) 


UDC11 Universal Digital Controller (not supported in 
RSX-11M-PLUS systems) 


DA11-B Parallel Unibus' Link (not supported in 
RSX-11M-PLUS systems) 


DLI1-E Asynchronous Communication Line Interface (not 
supported in RSX-11M-PLUS systems) 


DMC11 Synchronous Communication Line Interface 


DP1l Synchronous Communication Line Interface (not 
Supported in RSX-11M-PLUS systems) 


DQ11 Synchronous Communication Line Interface (not 
supported in RSX-11M-PLUS systems) 


DU11 Synchronous Communication Line Interface (not 
supported in RSX-11M-PLUS systems) 


DUPI1 Synchronous Communication Line Interface 


DH11 or DHVI11 Asynchronous Communications Line 
Multiplexer 


DL11-A/DL11-B/DL11-C/DL11-D/DL11-E Asynchronous 
Communications Line interface (DL11-B, DLiIi-E, DPili, 
DQ11, and DU11l are not supported in RSX-11M-PLUS 
systems) 

DZ11 Asynchronous Communications Line Multiplexer 


Reserved for customer use (not used by DIGITAL) 
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1.7.5.2 Pseudo-Device Names - A pseudo-device is a logical device 
that can normally be redirected by the operator to another physical 
device unit at any time, without requiring changes in programs’ that 
reference the pseudo-device. Dynamic redirection of a physical device 
unit affects all tasks in the system; reassignment by means of the 
MCR REASSIGN command affects only one task. The following 
pseudo-devices are supported, as indicated: 


Code Device 

CL Console listing, normally the line printer. 

Co Console output, normally the main operator's console. 
HT Network remote terminal 

LB System library device, normally the device from which 


the system was bootstrapped. For example, LB: is the 
device that tasks such as TKB and MAC access for 
default library files. 


NL Null device. 

NS Network pseudo-device for NSP. 

NX Network pseudo-device for DLX. 

RD On-line reconfiguration pseudo-device (RSX-1L1M-PLUS 
only). 

SP Spooling scratch disk device. 

SY User default device. On nonmultiuser systems, SY: is 
normally the disk from which the system was 
bootstrapped. On multiuser systems, SY: is normally 


the defauit login device. 
VD Virtual Device. 


DT Pseudo-input terminal; TIO: is the terminal from 
which a task was requested. 


The pseudo-device TI cannot be redirected, since such 
redirection would have to be handled on a per-task 
rather than a system-wide basis (that is, change the TI 
device for one task without affecting the TI 
assignments for other tasks). 


VT Virtual terminal. Used by some RSX-11M~PLUS offspring 
tasks as TI: for command and data I/O. (Supported in 
RSX-11M-PLUS systems only). 


1.7.6 The GLUNS Macro: Retrieving LUN Information 


The Get LUN Information macro requests that information about a 
LUN-physical device unit association be returned in a 6-word buffer 
specified by the issuing task. Upon successful completion of the 
directive processing, the buffer contains the information listed in 
Table 1-1, as appropriate for the specific device. All three forms of 
the macro call may be used. It is issued from a MACRO-1l program in 
the following way: 


GLUNS lun,buf 
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lun 


The logical unit number associated with the physical device unit 
for which information is requested. 


buf 
The 6-word buffer to which information is returned. 


For example, to request information on the disk unit associated with 
LUN 8, the following call is issued: 


GLUNSC 8.,IOBUF 


Table 1-1 
Get LUN Information 


Numerical Offset Symbolic Offset 
0 


G. LUNA Name of device associated with 
LUN (ASCII bytes) 


1 0 G. LUNU Unit number of associated device 


1 G.LUFB Driver flag value. Returned as 
200 octal if the driver is 
resident, or as 0 if a loadable 
driver is not in the system 


2 G.Lucwl First device characteristics 
word: 

0 (U.CW1) (DV.REC) | Unit record-oriented device (for 

example, card reader, line 


printer) (1 = yes) 

1 (DV.CCL) | Carriage-control device (for 
example, line printer, terminal) 
(1 = yes) 

2 (DV.TTY) | Terminal device (1 = yes) 


3 (DV.DIR) | Directory device (for example, 
DECtape, disk) (1 = yes) 


4 (DV.SDI) | Single directory device (for 
example, ANSI-standard magtape) 
(1 = yes) 


5 (DV.SQD) | Sequential device (for example, 
ANSI-standard magtape) (1 = yes) 


6 (DV.MSD) | Mass storage device (for example, 
disks and tapes) (1 = yes) 


1. The following word and bit symbols shown in parentheses are symbols used in 
defining and referencing corresponding items in the device UCB. 


(continued on next page) 
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Table 1-1 (Cont.) 
Get LUN Information 


Numerical offset Symbolic oeESet 


(DV.UMD) | User-mode diagnostics supported 


(1 = yes) 

8 (DV.EXT) | Device supports 22-bit direct 
addressing 

9 (DV.SWL) | Unit software write-locked 
(1 = yes) 

10 | (DV.ISP) | Input spooled device (1 = yes) 

11 (DV.OSP) | Output spooled device (1 = yes) 

12 (DV.PSE) | Pseudo-device (1 = yes) 
communications channel for 


Digital network support (for 
example, DP1l, DU11) (1 = yes) 


14 (DV.F1l1) | Device mountable as a FILES-11 
device (for example, disk or 


13 (DV.COM) | Device mountable as a 
DECtape) (1 = yes) 


15 (DV.MNT) | Device mountable (logical OR of 
bits 13 and 14) (1 = yes) 
3 G.LUCW+02 Second device characteristics 
word: 
(U.CW2) (U2.xxx) Device-specific information 
4 G.LUCW+04 Third device characteristics 
word: 
(U.CW3) (U3.xxx) | Device-specific information2 
5 G.LUCW+06 Fourth device characteristics 
word: 
(U .CW4) Default buffer size (for example, 


for disks, and line length for 
terminals). 


2. For mass storage devices, such as disks, DECtape, and DECtape II, this is 
the number of blocks (maximum logical block number plus one). For the proper 
use of the RX211/RxX02 flexible disk, it is important to be able to test 
G.LUCW+4 to determine the media density. 
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The example included below illustrates the use of the three forms of 
the GLUNS macro. 


DATA DEFINITIONS 


we ~S we 


GETLUN: GLUNS 6,DSKBUF ; GENERATE DPB 


EXECUTABLE SECTION 


me =e Ne 


DIRS #GETLUN ; EXECUTE DIRECTIVE 


GLUNSC 6,DSKBUF ; GENERATE DPB IN SEPARATE PROGRAM 
° ; SECTION, THEN GENERATE CODE TO 
° ; EXECUTE THE DIRECTIVE 
GLUNSS #6,#DSKBUF ; GENERATE DPB ON STACK, THEN 
; EXECUTE DIRECTIVE 


1.7.7 The ASTX$S Macro: Terminating AST Service 


The AST Service Exit macro is used to terminate execution of an AST 
service routine. All forms of the macro are provided. However, the 
S-form is preferred because it requires less space and executes at 
least as fast as the ASTXS or ASTXSC form of the macro. The macro is 
issued in the following way: 


ASTXSS_ [err] 


err 


An optional argument which specifies the address of an error 
routine to which control branches if the directive is rejected. 


On completion of the operation specified in this macro call, if 
another AST is queued and asynchronous system traps have not been 
disabled, then the next AST is immediately entered. Otherwise, the 
task's state before the AST was entered is restored (it is the AST 
service routine's responsibility to save and restore the registers it 
uses). 


1.7.8 The WTSE$ Macro: Waiting for an Event Flag 


The Wait For Single Event Flag macro instructs the system to suspend 
execution of the issuing task until the event flag specified in the 
macro call is set. This macro is extremely useful in synchronizing 
activity on completion of an I/O operation. All three forms of the 
macro call may be used. It is issued as follows: 


WTSES efn 
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efn 


The event flag number. 


WTSES causes the task to be blocked from execution until the specified 
event flag is set. Frequently, an efn parameter is also included ina 
QIO$ macro call, and the event flag is set on completion of the I/0 
operation specified in that call. The following example illustrates 
task blocking until the setting of the specified event flag occurs. 
This example also illustrates the use of the three forms of the macro 
call. 


DATA DEFINITIONS 


me we Se 


WAIT: WTSES 5 
IOSB: -BLKW 2 


GENERATE DPB 
1/O STATUS BLOCK 


we se 


EXECUTABLE SECTION 


=e we WO 


ALUNSS #14.,#"MM 
QIOSC IO.ATT,14.,5 
DIRS #WAIT 


ASSIGN LUN 14 TO MAGTAPE UNIT ZERO 
ATTACH DEVICE 
EXECUTE WAITFOR DIRECTIVE 


ue WO Ne 


QIOSS #10.RLB,#14.,#2,,#IOSB,,<#BUF,#80.> 
° ; READ RECORD, USE EFN2 


WTSESS #2 WAIT FOR READ TO COMPLETE 


~e 


QIOSC IO.WLB,14.,3,,I0SB,,<BUF,80.> 
‘ ; WRITE RECORD, USE EFN3 


WAIT FOR WRITE TO COMPLETE 


=e 


QIOSscC IO0.DET,14. DETACH DEVICE 


=e 


1.8 STANDARD I/O FUNCTIONS 


The number of input/output operations that can be specified by means 
of the QIO directive is large. A particular operation can be 
requested by including the appropriate function code as the first 
parameter of a QI0 macro cali. Certain functions are standard. These 
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functions are almost totally device independent and can thus be 
requested for nearly every device described in this manual. Others 
are device dependent and are specific to the operation of only one or 
two I/0 devices. This section summarizes the function codes and 
characteristics of the following device-independent I/O operations: 


@ Attach to an I/0 device 

@ Detach from an I/O device 
e Cancel I/O requests 

e Read a logical block 

@e Read a virtual block 

e Write a logical block 

e Write a virtual block 


For certain physical device units discussed in this manual, a standard 
I/O function may be described as being a NOP. This means that no 
operation is performed as a result of specifying the function, and an 
I/O status code of IS.SUC is returned in the I/0 status block 
specified in the QIO macro call. 


In the following descriptions and in formats shown in subsequent 
chapters, the five QIO directive parameters lun, efn, pri, isb, and 
ast are represented by the ellipsis (...) (see Section 1.5.1). 


1.8.1 IO.ATT: Attaching to an I/O Device 


The function code I0.ATT is specified by a user task when that task 
requires exclusive use of an I/O device. This function code is 
included as the first parameter of a QIO macro call in the following 
way: 


QIOSC IO.ATT,... 


Successful completion of an IO.ATT request causes the specified 
physical device unit to be dedicated for exclusive use by the issuing 
task. This enables the task to process input or output in an unbroken 
stream and is especially useful on sequential, non-file-oriented 
devices such as terminals, card readers, and line printers. An 
attached physical device unit remains under control of the issuing 
task until it is explicitly detached by that task. To detach the 
device, the task can specify any LUN previously assigned to the 
attached device. 


While a physical device unit is attached, the I/O driver for that unit 
dequeues only I/O requests issued by the task that issued the attach. 
Thus, a request to attach a device unit already attached by another 
task will not be processed until the attachment is broken and no 
higher priority request exists for the unit. A LUN that is associated 
with an attached physical device unit may not be reassigned by means 
of an Assign LUN directive except when at least one LUN is still 
assigned to the attached device. 
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If the task that issued an attach function exits or is aborted before 
it issues a corresponding detach, the Executive automatically detaches 
the physical device unit. 


1.8.2 I0.DET: Detaching from an I/O Device 


The function code IO.DET is used to detach a physical device unit that 
has been previously attached by means of an I0.ATT request for 
exclusive use of the issuing task. This function code is included as 
the first parameter of a QIO macro call in the following way: 


QIOSC LOSDET 7 eas 
The LUN specifications of both IO.ATT and IO.DET must be the same, as 
in the following example, which also illustrates the use of S- forms 


of several macro calls. 


-MCALL ALUNSS,QIOSS 
ALUNSS #14.,#"CR ; ASSOCIATE CARD READER WITH LUN 14 


QIOSss #IO.ATT, #14. ; ATTACH CARD READER 


LOOP: QIOSS #IO.RLB,#14.,... READ CARD 


=e 


QIOSsS #IO.DET, #14. ; DETACH CARD READER 


1.8.3 IO.KIL: Canceling I/O Requests 


The function IO.KIL is issued by a task to cancel all of that task's 
I/O requests for a particular physical device unit. 


For I/O requests waiting for service -- that is, in the I/O driver's 
queue -- a status code of IE.ABO is returned in the I/O status block. 
An event flag is set, if specified. But any AST service routine that 
may have been specified is not initiated. 


For I/O requests being processed by an I/O driver -- other than the 
disk or DECtape drivers ~- the IE.ABO status code is returned. Other 
status information (byte count, and so forth) is also returned in’ the 
I/O status block. An AST, if specified, is activated. 


For disk, DECtape, or DECtape II I/O requests being processed when an 
IO.KIL is issued, the IO.KIL acts as a NOP. The request is allowed to 
complete, except in the case in which a DECtape transfer is blocked by 
a select error. Because disk and DECtape operate quickly, IO.KIL 
Simply causes the return of IS.SUC in the I/O status block. 


This function code is included as the first parameter of a QIO macro 
in the following way: 


QIOSC IO.KIL,... 


IO.KIL is useful in such special cases as canceling an I/O request on 
a physical device unit from which a response is overdue (for example, 
a read on a paper tape reader). 
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1.8.4 IO.RLB: Reading a Logical Block 

The function code IO.RLB is specified by a task to read a block of 
data from the physical device unit specified in the macro call. This 
function code is included as the first parameter of a QIO macro in the 
following way: 


QIOSC IO.RLB,...,<Stadd,size,pn> 


stadd 


The starting address of the data buffer. 


size 


The data buffer size in bytes. 


pn 


One to four optional parameters, used to specify such additional 
information as block numbers for certain devices. 


1.8.5 IO.RVB: Reading a Virtual Block 


The function code IO.RVB is used to read a virtual block of data from 
the physical device unit specified in the macro call. A "virtual" 
block indicates a relative block position within a file and is 
identical to a "logical" block for such sequential, record-oriented 
devices as terminals and card readers. For these sequential, 
record-oriented devices, I0.RVB is converted to I0.RLB before being 
issued. 


NOTE 
Any subfunction bits specified in the 
IO.RVB request (see Sections 2.3.1 and 


SeSeL) sare stripped off in this 
conversion. 


It is recommended that all tasks use virtual rather than logical 
reads. However, if a virtual read is issued for a file-structured 
device (disk, DECtape, or DECtape II), the user must ensure that a 
file is open on the specified physical device unit. This function 
code is included as the first parameter of a QIO macro call in the 
following way: 


QIOSC IO.RVB,...,<Sstadd,size,pn> 


stadd 


The starting address of the data buffer. 


size 


The data buffer size in bytes. 


RSX-11M/M-PLUS INPUT/OUTPUT 


pn 


One to four optional parameters, used to specify such additional 
information as block numbers for certain devices. 


1.8.6 IO.WLB: Writing a Logical Block 


The function code IO.WLB is specified by a task to write a block of 
data to the physical device unit specified in the macro call. This 
function code is included as the first parameter of a QIO macro call 
in the following way: 


QTosc IO.WLB,...,<stadd,size,pn> 


stadd 


The starting address of the data buffer. 


size 


The data buffer in bytes. 


pn 


One to four optional parameters, used to specify such additional 
information as block numbers’ or format control characters for 
certain devices. 


1.8.7 IO.WVB: Writing a Virtual Block 


The function code IO.WVB is used to write a virtual block of data to a 
physical device unit. A "virtual" block indicates a block position 
relative to the start of a file. For sequential, record-oriented 
devices such as terminals and line printers, the function IO.WVB is 
converted to IO.WLB. 


NOTE 


Any subfunction bits specified in the 
IO.WVB request (see Sections 2.3.1 and 
3.3.1) are stripped OLE in this 
conversion. 


It is recommended that all tasks use virtual rather than logical 
writes. However, if a virtual write is issued for a file-structured 
device (disk, DECtape, or DECtape II), the user must ensure that a 
file is open on the specified physical device unit. This function 
code is included as the first parameter of a QIO macro call in _ the 
following way: 


OIOSc IO.WVB,...,<Stadd,size,pn> 
Sstadd 


The starting address of the data buffer. 
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size 
The data buffer size in bytes. 
pn 


One to four optional parameters, used to specify such additional 
information as block numbers’ or format control characters for 
certain devices. 


1.8.8 User-Mode Diagnostic Functions 


The I/O function code subfunction bit, I0.UMD, provides support for 
user-mode diagnostics. To perform a diagnostic function, you must 
specify in the QIO directive parameter block the logical OR of IQ.UMD 
and the function you want to perform. For example, to perform a 
diagnostic Read Logical Block operation, specify IO.RLB!IQ.UMD as' the 
I/O function code parameter to the QIO directive. You can perform 
standard I/O functions such as Read Logical Block, Write Logical 
Block, Attach to Device, and Detach from Device in diagnostic mode. 


Support for user-mode diagnostics is always present for RSX-11M-PLUS, 
but not all drivers support user-mode diagnostic functions. 
Unpredictable device and driver behavior results when you set the 
IQ.UMD subfunction bit in QIOs that are directed to the device if it 
does not support user-mode diagnostics. Problems can be avoided if 
you do a Get LUN directive and check the user-mode diagnostics bit 
before emitting the user-mode diagnostic QIO. 


To support user-mode diagnostics, the DV.UMD bit in the UCB must be 
set. DV.UMD is at offset U.CWl in the UCB. 


In addition to standard I/O functions, RSX-11M-PLUS provides’ the 
following device-dependent, user-mode diagnostic functions: 


1. Disk diagnostic functions 


e I0.HMS Home seek or recalibrate 
® I0.BLS Block seek (explicit seek) 
e I0O.OFF Offset position 

e I0.RDH Read disk header 

e I0.WDH Write disk header 

e IO.WCK Writecheck 


2. DECtape diagnostic functions 
e I0.RNF Read block number forward 
e I1I0.RNR Read block number reverse 
3. Magtape diagnostic functions 
e I0.LPC Read longitudinal parity character 
e I0.ERS Erase tape 


UMDIOS is the macro that defines these functions. 


RSX-11M/M-PLUS INPUT/OUTPUT 


To execute a uSer-mode diagnostic function, you must first attach for 
diagnostics using I/0 function code I0.ATT!IQ.UMD. Execute the 
diagnostic functions and then detach. 


The parameter list in words 1 through 6 of the DPB should contain the 
following information: 


e I/0 buffer address 
e I/0 buffer size 


e Offset factor for disks with offSet recovery (to determine the 
offset factor, refer to the offset register in the hardware 
reference manual); this parameter is not used if the device 
does not have offset recovery. 


e Double-precision logical block number 
e User's register buffer address (the I/O driver copies 


hardware registers to this buffer in the user's program); 
a hardware reference manual for the length of the address 


Q 
MD cfr 
On 


A typical DPB for a diagnostic function might look like the following: 


SDSKPB:: 
~ BYTE 3,12. 3; Size of the DPB, QIOWAIT directive code 
~WORD IO.WDH!IQ.UMD 3 I/O function code 
~WORD THELUN ; Logical Unit Number 
~BYTE THEEFN,0 3; Event flag number 
»WORD SIOSTS ; I/O status block address 
~WORD 0 ; AST address 
SIOBUF:: .WORD 0 ; Buffer address 
~WORD 0 3; Transfer size in bytes 
~WORD 0 ; Device dependent 
SLBH:: «WORD 0 3; High-order logical block number 
SLBL:: «WORD 0 ; Low-order logical block number 
»WORD SRGBUF 7 Register buffer address 


The user~mode diagnostic functions return either Success (IS.SUC) or 
Device Not Ready (IE.DNR). No other error codes are returned. All 
error recovery is completely up to the user. Any errors that occur 
will not be logged in the error log. 


A typical program fragment, using the user-mode diagnostic functions, 
might look like the following: 


»~MCALL UMDIOS,ALUNSS,QIOSS 
UMDIOS ; Define diagnostic functions 
ALUNSS #14.,#"DM,#0 ; Associate DMO with lun 14 
QIOSS #14.,#"DM,#0 ; Associate DMO with lun 14 


QIOSS #IO.ATT!IQ.UMD, #14. ; Attach DM for diagnostic I/0 


QIOSS #IO.RDH!IQ.UMD, #14.,,,,,<#SIOBUF,#512.,,#LBH,#LBL,#SRGBUF> ; Read disk header 


QIOSssS #IO.RLB!IQ.UMD,#14.,,,,,<#SIOBUF,#512.,,#LBH,#LBL,#SRGBUF> ; Read logical block 


QIoss #10.DET!IQ.UMD, #14. ; Detach DM 
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1.9 I/O COMPLETION 


When an I/O request has been completed, either successfully or 
unsuccessfully, one or more actions may be taken by the Executive. 
Selection of return conditions depends on the parameters included in 
the QIO macro call. There are three major returns: 


1. A Significant event is declared on completion of an I/O 
operation. Tf an efn parameter was included in the I/0 
request, the corresponding event flag is set. 


2. If an isb parameter was specified in the QIO macro call, a 
code identifying the type of success or failure is returned 
in the low-order byte of the first word of the I/O status 
block at the location represented by isb. 


This status return code is of the form IS.xxx (Success) or 
IE.xxx (error). For example, if the device accessed by the 
I/O request is not ready, a status code of IE.DNR is returned 
in isb. The section below (Return Codes) summarizes general 
codes returned by most of the drivers described in this 
manual. 


If the isb parameter was omitted, the requesting task cannot 
determine whether the I/O request was successfully completed. 
A carry clear return from the directive itself simply means 
that the directive was accepted and the I/O request was 
queued, not that the actual input/output operation was 
successfully performed. 

3. If an ast parameter was specified in the QIO macro call, a 
branch to the AST service routine that begins at the location 
identified by ast occurs on completion of the I/O operation. 


See Section 1.5.3 for a detailed description of AST service 
routines. 


1.10 RETURN CODES 


There are two kinds of status conditions recognized and handled by 
RSX-11M/M-PLUS when they occur in I/O requests: 


@ Directive conditions, which indicate the acceptance or 
rejection of the QIO directive itself 


e I/0 status conditions, which indicate the success or failure 
of the I/O operation 


Directive conditions relevant to I/O operations may indicate any of 
the following: 


e Directive acceptance 

e Invalid buffer specification 

e Invalid efn parameter 

@ Invalid lun parameter 

e Invalid DIC number or DPB size 
e Unassigned LUN 


e Insufficient memory 
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A code indicating the acceptance or rejection of a directive is 
returned to the Directive Status Word at symbolic location S$DSW. This 
location can be tested to determine the type of directive condition. 


I/O conditions indicate the success or failure of the I/O operation 
specified in the QIO directive. I/O driver errors include such 
conditions as device not ready, privilege violation, file already 
open, or write-locked device. If an isb parameter is included in the 
QIO directive, identifying the address of a 2-word I/O status’ block, 
an I/O status code is returned in the low-order byte of the first word 
of this block on completion of the I/O operation. This code is a 
binary value corresponding to a symbolic name of the form IS.xxx or 
IE.xxx. The low-order byte of the word can be tested symbolically, by 
name, to determine the type of status return. The correspondence 
between global symbolic names and directive and I/O completion status 
codes is defined in the system object module library. Local symbolic 
definitions may also be obtained by the DRERRS and IOERRS macros, 
which reside in the System Macro Library and are summarized in 
Appendix B. 


Binary values of status codes always have the following meanings: 


Code Meaning 
Positive (greater than 0) Successful completion 
0 Operation still pending 
Negative Unsuccessful completion 


A pending operation means that the I/O request is still in the queue 
of requests for the respective driver, or the driver has not yet 
completely serviced the request. 


1.10.1 Directive Conditions 
Table 1-2 summarizes the directive conditions that may be encountered 
in QIO directives. The acceptance condition is first, followed by 


error codes indicating various reasons for rejection, in alphabetical 
order. 


Table 1-2 
Directive Conditions 


a ee 


IS.SUC 


Directive accepted 


The first six parameters of the QIO directive were 
valid, and sufficient dynamic memory was available 
to allocate an I/O packet. The directive is 
accepted. 


The I/O status block or the QIO DPB was outside of 
the issuing task's address space or was not aligned 
on a word boundary. 


(continued on next page) 
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Table 1-2 (Cont.) 
Directive Conditions 


IE. IEF Invalid event flag number 


The efn specification in a QIO directive was less 
than 0 or greater than 96. 


TE.ILuU Invalid logical unit number 


The lun specification in a QIO directive was 
invalid for the issuing task. For example, there 
were only 5 logical unit numbers associated with 
the task, and the value specified for lun was 
greater than 5. 


IE.SDP Invalid DIC number or DPB size 


The directive identification code (DIC) or the size 
of the Directive Parameter Block (DPB) was 
incorrect; the legal range for a DIC is from 1 
through 127, and all DIC values must be odd. Each 
individual directive requires a DPB of a certain 
size. If the size is not correct for the 
particular directive, this code is’ returned. The 
size of the QIO DPB is always 12 words. 


TE.ULN Unassigned LUN 


The logical unit number in the QIO directive was 
not associated with a physical device unit. The 
user may recover from this error by issuing a valid 
Assign LUN directive and then reissuing the 
rejected directive. 


TE.UPN Insufficient dynamic memory 


There was not enough dynamic memory to allocate an 
I/O packet for the I/O request. The user can try 
again later by blocking the task with a Waitfor 
Significant Event directive. Note that Waitfor 
Significant Event is the only effective way for the 
issuing task to block its execution, since other 
directives that could be used for this purpose 
themselves require dynamic memory for their 
execution (for example, Mark Time). 


1.10.2 I/0 Status Conditions 


The following list summarizes status codes that may be returned in the 
I/O status block specified in the QIO directive on completion of the 
I/O request. The I/0 status block is a 2-word block with the 
following format: 


e The low-order byte of the first word receives a status code of 
the form IS.xxx or IE.xxx on completion of the I/O operation. 


e The high-order byte of the first word is usually device 
dependent; in cases where the user might find information in 
this byte helpful, this manual identifies that information. 
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e The second word contains the number of bytes transferred or 
processed if the operation is successful and involves reading 
or writing. 


If the isb parameter of the QIO directive is omitted, this information 
is not returned. 


The following illustrates a sample 2-word I/O status block on 
completion of a terminal read operation: 


a 0 Byte 


where -10 is the status code for IE.EOF (end of file). If this code 
is returned, it indicates that input was terminated by typing CTRL/Z, 
which is the end-of-file termination sequence on a terminal. 


To test for a particular error condition, the user generally compares 
the low-order byte of the first word of the I/O status block with a 
symbolic value, as in the following: 


CMPB #IE.DNR,IOSB ae 


However, to test for certain types of successful completion of the I/O 
operation, the entire word value must be compared. For example, if a 
carriage return terminated a line of input from the terminal, a 
successful completion code of IS.CR is returned in the I/O status | 
block. If an Escape (or Altmode) character was the terminator, a code 
of IS.ESC is’ returned. To check for these codes, the user should 
first test the low-order byte of the first word of the block for 
IS.SUC and then test the full word for IS.CC, IS.CR, IS.ESC, or 
IS.ESQ. (Other success codes that must be read in this manner are 
listed in Appendix B, Section B.1.2.) 


Note that both of the following comparisons will test as equal since 
the low-order byte in both cases is +l. 


CMP #I1S.CR,IOSB 

CMPB #I1S.SUC,IOSB 
In the case of a successful completion where the carriage return is 
the terminal indicator (IS.CR), the following illustrates the status 
block: 


al 0 Byte 


1 Number of bytes read 
(excluding the CR) 


where 15 is the octal code for carriage return and +1 is the _ status 
code for successful completion. 


The codes described in Table 1-3 are general status codes that apply 
to the majority of devices presented in subsequent chapters. Error 
codes specific to only one or two drivers are described only in 
relation to the devices for which they are returned. The list below 
describes successful and pending codes first, then error codes in 
alphabetical order. 


IS. PND 


IE.ABO 


IE.ALN 


IE.BAD 


IE.BBE 


IE.BLK 


IE.BYT 
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Table 1-3 
I/O Status Conditions 


Successful completion 


The I/O operation specified in the QIO directive 
was completed successfully. The second word of the 
I/O status block can be examined to determine the 
number of bytes processed, if the operation 
involved reading or writing. 


I/O request pending 


The I/O operation specified in the QIO directive 
has not yet been executed. The I/0 status block is 
filled with Os. 


Operation aborted 


The specified I/O operation was cancelled with 
IO.KIL while in progress or while still in the I/0 
queue. 


File already open 


The task attempted to open a file on the physical 
device unit associated with the specified LUN, but 
a file has already been opened by the issuing task 
on that LUN. 


Bad parameter 


An illegal specification was supplied for one or 
more of the device-dependent QIO parameters (words 
6-11). For example, a bad channel number or gain 
code was specified in an analog-to-digital 
converter I/O operation. 


Bad block on device 


One or more bad blocks were found by executing the 
BAD utility. Data cannot be written on bad blocks. 


Illegal block number 


An illegal block number was specified for a 
file-structured physical device unit. This code is 
returned, for example, if block 4800 is’ specified 
for an RKO5 disk, on which legal block numbers 
extend from 0 through 4799. 
| 


Byte-aligned buffer specified. 


Byte alignment was specified for a buffer, but only 
word (or double-word) alignment is legal for the 
physical device unit. For example, a disk function | 
requiring word alignment was requested, but the 
buffer was aligned on a byte boundary. 
Alternately, the length of a buffer was not an 
appropriate multiple of bytes. For example, all 
RPO3 disk transfers must’ be an even multiple of 
four bytes. 


(continued on next page) 
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Table 1-3 (Cont.) 
I/O Status Conditions 


Device already attached 


The physical device unit specified in an I0.ATT 
function was already attached to the issuing task. 


This code indicates that the issuing task has 
already attached the desired physical device unit, 
not that the unit was attached by another task. 


Device not attached 


The physical device unit specified in an I0O.DET 
function was not attached to the issuing task. 
This code has no bearing on the attachment’ status 
with respect to other tasks. 


Device not ready 


The physical device unit specified in the QIO 
directive was not ready to perform the desired I/0 
operation. This code is often returned as_ the 
result of an interrupt time-out; that is, a 
"reasonable" amount of time has passed, and_ the 
physical device unit has not responded. 


End-of-file encountered 


An end-of-file mark, record, or control character 
was recognized on the input device. 


Fatal hardware error 


Controller is physically unable to reach the 
location where input/output is to be performed on 
the device. The operation cannot be completed. 


Illegal function 


A function code was specified in an I/O request 
that was illegal for the specified physical device 
unit. This code is returned if the task attempts 
to execute an illegal function or if, for example, 
a read function is requested on an_  output-only 
device, such as the line printer. 


File not open 


The task attempted to close a file on the physical 
device unit associated with the specified LUN, but 
no file was currently open on that LUN. 


Insufficient buffer space 


Dynamic storage space has been depleted, and there 
was insufficient buffer space available to allocate 
a secondary control block. For exampie, if a task 
attempts to open a file, buffer space for the 
window and file control block must be supplied by 
the Executive. This code is returned when there is 
not enough space for such an operation. 


(continued on next page) 
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Table .i=3°. (Conts,) 
I/O Status Conditions 


IE.OFL Device off line 


The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not in 


| the configuration. 

IE.OVR Illegal read overlay request 
A read overlay was requested and the physical 
device unit specified in the QIO directive was not 
the physical device unit from which the task was 
installed. The read overlay function can only be 


executed on the physical device unit from which the 
task image containing the overlays was installed. 


IE.PRI Privilege violation 


The task that issued a request was not privileged 
to execute that request. For example, for the 
UDC11 and LPS11, a checkpointable task attempted to 
connect to interrupts or to execute a synchronous 
sampling function. 


LE «SPC Illegal address space 
The buffer requested for a read or write request 
waS partially or totally outside the address space 
of the issuing task. Alternately, a byte count of 
0 was specified. 

IE.VER Unrecoverable error 
After the system's standard number of retries have 
been attempted upon encountering an error, the 
operation still could not be completed. This code 
is returned in the case of parity, CRC, or similar 
errors. 

TE.WCK Write check error 
An error waS detected during the check (read) 
following a write operation. 

IE.WLK Write-locked device 


The task attempted to write on a_ewrite-locked 


physical device unit. 
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1.11 POWER-FAIL RECOVERY PROCEDURES FOR DISKS AND DECTAPE 


Power-fail recovery recommendations for various devices are included 
in the following chapters, as appropriate, to assist the user in 
restoring device operation after a power failure. For disks’ and 
DECtape, it is recommended that power recovery ASTs be used. The AST 
service routine should provide a sufficient time delay, prior to 
returning for normal I/0 operations, that will allow the disk to 
attain normal operating speed before actually attempting read and 
write operations. 


If QIOs are being used for disk or DECtape I/O operations during 
power-fail recovery, an IE.DNR error status may be returned if the 
device is not up to operating speed when the request is issued. When 
this error iS returned, it is recommended that the user task wait a 
sufficient time for the device to attain operating speed, and attempt 
the I/0 operation again prior to reporting an error. For example, an 
RKO5 disk may require approximately 1 minute to attain operating speed 
after a power failure. 


CHAPTER 2 


FULL-DUPLEX TERMINAL DRIVER 


2.1 INTRODUCTION 


Two terminal drivers are available as SYSGEN options for use in 
RSX-11M systems: 


1. 


A compact, half-duplex terminal driver for use with a wide 
variety of terminals, containing all basic features required 
for RSX-11M terminal support. (This terminal driver is not 
available on RSX-11M-PLUS systems.) This terminal driver is 
described in Chapter 3. 

A full-duplex terminal driver, as described in this chapter, 
containing all features of the half-duplex terminal driver, 
plus the following: 

@ Full-duplex operation 

@e Type-ahead buffering 

e Eight-bit characters 

@ Detection of hard receive errors 

e Increased byte transfer length (8128 bytes) 

e Additional terminal characteristics 

e Additional terminal types 

@e Optional time-out on solicited and/or unsolicited input 

@® Device-independent cursor control 


e Redisplay of prompt buffer upon CTRL/R or CTRL/U 


@e Automatic XOFF character generation upon completion of a 
read (except when in the full-duplex mode), if requested 


® Autobaud speed detection 


@ Added hardware support 


Note that either terminal driver can be selected during RSX-11M 


SYSGEN,. 


only. 


RSX-11M-PLUS systems use the full-duplex terminal driver 
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Throughout the remainder of this chapter, references made to MCR can 
generally be applied to other command line interpreters (for example, 
DCL). In addition, the prompt displayed on a terminal in response to 
invoking a command line interpreter will be appropriate for the 
specific command line interpreter in use. For example, when MCR is 
invoked, the MCR prompt is displayed as follows: 


MCR> 
Terminal driver support is provided for a variety of terminal devices, 


as listed in Table 2-1. Subsequent sections describe each device in 
greater detail. 


Table 2-1 
Supported Terminal Devices 


Model Columns Lines/, Character Baud 


ASR-33/35 72 64 110 

KSR-33/35 72 64 110 

LA12 132 96 50-9600 yes yes 
LA100 i 3Z 96 110-9600 yes yes 
LA30-P 80 64 300 

LA30-S 80 64 110-300 

LA34 132 96 110-300 yes yes 
LA36 132 64-96 110-300 yes yes? 
LA38 132 96 110-300 yes yes 
LA120 132 96 50-9600 yes yes 
LA180S 132 96 300-9600 yes 
LQPO02 132/158 110-9600 

LA5O 80/96/132 110-4800 

RTO2 64 iL: 64 110-1200 

RTO2-C 64 a 64 110-1200 

VTO5B 72 20 64 110-2400 yes 

VT50 80 12 64 110-9600 

VT50H 80 12 64 110-9600 

VT52 80 24 96 110-9600 yes yes 
VT55 80 24 96 110-9600 yes yes 
VT6l 80 24 96 110-9600 yes yes 
VT1LOO 80-132 24 96 50-9600 yes yes 
VT101 80-132 24 96 50-19200 yes yes 
VT102 80-132 24 96 50-9600 yes yes 
VT105 80-132 24 96 50-19200 yes yes 
vTl25 | 80-132 24 96 50-9600 yes yes 
VT131 80-132 24 96 50-19200 yes yes 
VT132 80-132 24 96 50-19200 yes yes 


1. Applies only to video terminals. 


2. Only for 96-character terminal. The terminal driver supports the 
terminal interfaces summarized in Table 2-2. These interfaces are 
described in greater detail in Section 2.9. Programming is identical 
for all interfaces. 
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Table 2-2 
Standard Terminal Interfaces 


DH11 16-line multiplexerl 


8-line multiplexer2 


DHV11 


DH11-DM11-BB 


DJ11 


1 

| 
16-line multiplexer with modem control2 
16-line multiplexer 


DL11-A/B/C/D/E/W | Single-line interfaces 
DLV11-E/F | Single-line interfaces3 
DZ11 8-line multiplexer with modem control3 


1. Direct memory access’ (DMA) is Supported in the 
full-duplex terminal driver only. 


2. Full-duplex control only. For example, in the USA, a 
Bell 103A-type modem. 


3. DLV11 and DHV11 support with modem control is provided 
in the full-duplex terminal driver only. 


Terminal input lines can have a maximum length of 8128 (8K minus 64) 
bytes. Extra characters of an input line that exceed the maximum line 
length generally become an unsolicited input line if the terminal is 
not attached with typeahead enabled. 


2.1.1 ASR-33/35 Teletypes* 


The ASR-33 and ASR-35 Teletypes are asynchronous, hard-copy terminals. 
No paper-tape reader or punch capability is supported. 


2.1.2 KSR-33/35 Teletypes* 


The KSR-33 and KSR-35 Teletypes are asynchronous, hard-copy terminals. 


2.1.3 LA12 Portable Terminal 


The LA12 is a personal, portable, hard-copy terminal. 


2.1.4 LA100 DECprinter 


The LA100 is a desk-top, matrix, hard-copy terminal. 


1. Teletype is a registered trademark of the Teletype Corporation. 
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2.1.5 LA30 DECwriters 


The LA30 DECwriter is an asynchronous, hard-copy terminal that is 
capable of producing an original and one copy. The LA30-P is a 
parallel model and the LA30-S is a serial model. 


2.1.6 LA36 DECwriter 


The LA36 DECwriter is an asynchronous terminal that produces hard copy 
and operates in serial mode. It has an impact printer capable of 
generating multipart and special preprinted forms. The LA36 can 
receive and transmit both uppercase and lowercase characters. 


2.1.7 LA34/38 DECwriters 


The LA34 DECwriter is an asynchronous terminal that produces hard copy 
and uses a platen paper feed mechanism. 


The LA38 DECwriter includes a detachable tractor feed mechanism for 
use with continuous forms. 


2.1.8 LA1l20 DECwriter 


The LA120 DECwriter is a hard-copy, upper- and lowercase terminal, 
capable of printing multipart forms at speeds up to 180 
characters-per-second. Serial communications speed is selected from 
14 baud rates ranging from 50 to 9600 bps; split transmit and receive 
baud rates are supported by the terminal driver. Hardware features 
allow bidirectional printing for maximum printing speed, and also 
allow user-selected features, including font size, line spacing, tabs, 
Margins, and forms control. These functions can also be set up by the 
system by issuing appropriate ANSI-standard escape sequences. 


2.1.9 LA180S DECprinter 


The LA180S DECprinter is a serial version of the 1LA180. It is a 
print-only device (it has no keyboard) that can generate multipart 
forms. The LA180S can print uppercase and lowercase letters. 


2.1.9A LQPO2 Letter-Quality Printer 


The LOPO2 Letter-Quality Printer is a formed character, desktop 
printer incorporating daisywheel technology. This letter-quality 
printer offers over 100 character sets and handles’ regular office 
Stationery up to a maximum of 15 inches, but the print capacity is 
13.5 inches. The lines per inch and characters per inch are software 
selectable; characters at 10 and 12 and lines at 2, 3, 4, 6, and 8. 
At 10 characters per inch you get 132 columns and at 12 characters you 
get 158 columns. The buffer capacity is 256 characters. 
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2.1.9B LA50 Personal Printer 


The LAS5SO Personal Printer is a desktop dot-matrix impact printer. It 
has two print modes; text mode and enhanced print mode. In text 
mode, it prints at 100 characters per second. The enhanced print 
quality mode prints at 50 characters per second and creates a crisper, 
more uniform character than an ordinary dot-matrix printer. You can 
choose characters per inch at 10, 12, or 16 which gives columns at 80, 
96, or 132 and lines per inch can be 6, 8, or 12. The buffer capacity 
is 255 characters. 


2.1.10 RTO02 Alphanumeric Display Terminal and RTO2-C Badge 
Reader/Alphanumeric Display Terminal 


The RTO2 is a compact, alphanumeric display terminal designed for 
applications in which source data is primarily numeric. A shift key 
permits the entry of 30 discrete characters, including uppercase 


alphabetic characters. The RT02 can, however, receive and display 64 
characters. 


The RTO2-C model also contains a badge reader. This option provides a 
reliable method of identifying and controlling access to the PDP-1l or 
to a secure facility. Furthermore, data in a format corresponding to 
that of a badge (22-column fixed data) can be entered quickly. 
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2.1.11 VTO5B Alphanumeric Display Terminal 


The VTO5B is an alphanumeric display terminal that consists of a CRT 
display and a_ self-contained keyboard. From a programming point of 
view, it is equivalent to other terminalis, except that the VTO5B 
offers direct cursor addressing. 


2.1.12 VT50 Alphanumeric Display Terminal 


The VT50 is an alphanumeric display terminal that consists of a CRT 
display anda keyboard. It is similar to the VTO5B in operation, but 
does not offer direct cursor addressing. 


2.1.13 VT50H Alphanumeric Display Terminal 


The VT50H is an alphanumeric display terminal with CRT display, 
keyboard, and numeric pad. It offers direct cursor addressing. (The 
VT50H's direct cursor addressing is not compatible with that of the 
VTO5B.) 


2.1.14 VT52 Alphanumeric Display Terminal 


The VT52 is an upper- and lowercase alphanumeric terminal with numeric 
pad and direct cursor addressing. (The VT52's direct cursor 
addressing is compatible with that of the VT50H, not with that of the 
VTO5B.) The VT52 can be configured with a built-in thermal printer. 


2.1.15 VT55 Graphics Display Terminal 


The VT55 is similar to the VT52 in its operation as an alphanumeric 
terminal. The VT55 offers graphics display features that are not 
supported by RSX-11M, although the system allows a knowledgeable task 
to access the explicitly special features of the VT55. 


2.1.16 VT61 Alphanumeric Display Terminal 


The VT6l is an "intelligent" upper- and lowercase alphanumeric 
terminal with an integral microprocessor. It offers two 128-member 
character sets and numerous built-in functions for editing and forms 
Preparation as well as a block-transfer mode. (None of these special 
features is supported by RSX-11M.) 


2.1.17 VT100 DECscope 


The VT100 DECscope is an upper- and lowercase alphanumeric 
keyboard/video display terminal. It is capable of displaying 24 lines 
of 80 to 132 characters (each line). Serial communications speed is 
selected from baud rates ranging from 50 to 9600 bps. Hardware 
features allow user selection of display characteristics and functions 
including smooth scroll, reverse video, and so forth. These functions 
can also be set up by the system by issuing appropriate ANSI-standard 


FULL-DUPLEX TERMINAL DRIVER 


2.1.18 VT101 DECscope 


The VT101 DECscope is functionally identical to the VT100. However, 
it does not support the advanced video features. 


2.1.19 VT102 DECscope 


The VT102 DECscope is functionally identical to the VT100. However, 
it does not have any expansion capability and does not support the 
advanced video features. It has enhanced modem control and it 
includes a port for a printer. 


2.1.20 VT105 DECscope 


The VT105 DECscope is a video terminal. It has both alphanumeric and 
graphic display. The VT105 can display two graphs, two shaded graphs, 
or two strip charts. These graphs may have alphanumeric labels. 


2.1.21 VT131 DECScope 


The VT131 is the same as the VT102 with the addition of built-in 
editing features. 


2.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for terminals. A setting of 1 indicates that the 
described characteristic is true for terminals. 


Bit Setting Meaning 
0 1 Record-oriented device 
1 i. Carriage-control device 
2 1 Terminal device 
5 0 File structured device 
4 0 Single-directory device 
5 0 Sequential device 
6 0 Mass storage device 
d 0 User-mode diagnostics supported 
8 0 Device supports 22-bit direct addressing 
9 0 Unit software write-locked 
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Bit Setting Meaning 
10 0 Input spooled device 
1d 0 Output spooled device 
12 0 Pseudo device 
13 0 Device mountable as a communications 
channel 
14 0 Device mountable as a FILES-11 volume 
L5 0 Device mountable 


Words 3 and 4 of the buffer are undefined. Word 5 indicates the 
default buffer size (the width of the terminal carriage or display 
screen). 


2.3 QI10 MACRO 

Table 2-3 lists the standard and device-specific functions of the QIO 
macro that are valid for terminals. Some device-specific functions 
are options that may be selected during SYSGEN. 

Two device-specific functions, SF.SMC and SF.GMC, have nonstandard 


function names. These names are retained for compatibility with 


Table 2-3 
Standard and Device-Specific QIO Functions for Terminals 


Format Function 


STANDARD FUNCTIONS: 


OLOSC “TOsATTs 2-04 Attach device. 

OLOSC 10, DET; -s:.% Detach device. 

O1OSC: TOVKI bss Cancel I/O requests. 

QIOSC IO.RLB,...,<Stadd,size[,tmo]> READ logical block 
(read typed input into 
buffer). 

OIOSC IO.RVB,...,<stadd,size[,tmo]> READ virtual block 
(read typed input into 
buffer). 

QIOSC IO.WLB,...,<stadd,size,vfc> WRITE logical block 


(print buffer 
contents). 


OIOSC IO.WVB,...,<Stadd,size,vfc> WRITE virtual block 


(print buffer 
contents). 


Nee ee ssdeu was save 
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Table 2-3 


Standard and Device-Specific QIO Functions for Terminals 


a ee 


DEVICE-SPECIFIC FUNCTIONS: 
QIOSC IO.ATA,...,<ast, 
[parameter2][,ast2]>l 


QIOSC I0.CCO,...,<stadd,size,vfc> 


QIOSC SF.GMC,...,<stadd,size>l 


QOIOSC IO0.GTS,...,<stadd,size>l 
QIOSC IO.HNG,... 


QIOSC IO.RAL,...,<stadd,size[,tmo]> 
QIOSC IO.RNE,...,<stadd,size[,tmo]> 
QIOSC IO.RPR,...,<stadd,size, 


[tmo] ,pradd,prsize,vfe>l 


QIOSC IO.RST,...,<stadd,size[,tmo]> 


QIOSC IO.RTT,...,<stadd,size, 
ftmo] ,table> 


OQIOSC SF.SMC,...,<stadd,size>l 
QIOSC IO.WAL,...,<stadd,size,vfc> 


QIOSC IO.WBT,...,<stadd,size,vfe>l 


ast 


ATTACH device, specify 
unsolicited-input- 
character AST. 


CANCEL CTRL/O (if in 
effect), then write 
logical block. 


GET multiple 
characteristics. 


GET terminal support. 
HANGUP remote line. 


READ logical block, 
pass all bits. 


READ logical block, do 
not echo. 


READ logical block 
after prompt. 


READ logical block 
ended by special 
terminators. 


READ logical block 
ended by specified 
special terminator. 


SET multiple 
characteristics. 


WRITE logical block, 
pass all bits. 


WRITE logical block, 
break through any I/0 
conditions at 
terminal. 


The entry point for an unsolicited- input-character AST. 


parameter 2 


A number that can be used to identify this terminal as the 


source upon entry to an unsolicited character AST routine. 


1. SYSGEN options in RSX-11M. 


input 
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ast2 
The entry point for an unsolicited CTRL/C AST. 

pradd 
The starting address of the byte buffer where the prompt is 
stored. 

prsize 
The size of the pradd prompt buffer in bytes. The specified size 
must be greater than 0 and iess than or equal to 8128. The 
buffer must be within the task's address space. 

size 
The size of the stadd data buffer in bytes. The specified size 
must be greater than 0 and =Iless than or equal to 8128. The 
buffer must be within the task's address space. For SE.GMC, 
IO.GTS, and SF.SMC functions, size must be an even value. 

stadd 
The starting address of the data buffer. The address must be 
word aligned for SF.GMC, I0O.GTS, and SF.SMC; otherwise, stadd 
may be on a byte boundary. 

table 
The address of the 16-word special terminator table. 

tmo 
An optional time-out count in 10-second intervals for the 
full-duplex terminal driver. If 0 is specified, no time-out can 
occur. Time-out is the maximum time allowed between two input 
characters before the read is aborted. The maximum timeout value 
is 255. 

vic 


A character for vertical format control from Table 2-11 (see 
Section 2.7). 


2.3.1 Subfunction Bits 


Most device-specified functions supported by terminal drivers 
described in this section are selected using "subfunction bits." One 
Or more functions can be selected by ORing their relative bits in a 
QiG function. Table 2-4 contains a listing of QIO functions and 
relative subfunction bits that can be issued. 
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Each subfunction bit and subfunction selected when it is included ina 
QIO function is listed as follows: 


Symbolic 
Name Subfunction 

TF.AST Unsolicited-input-character AST 

TF.BIN Binary prompt 

TF .CCO Cancel CTRL/O 

TF.ESQ Recognize escape sequences 

TF.NOT Unsolicited input AST notification; unsolicited 
characters are stored in the type-ahead buffer 
until they are read by the task 

TF.RAL Read all bits 

TF.RCU Restore cursor position 

TF.RNE Read with no echo 

TF.RST Read with special terminators 

TF.TMO Read with time-out 

TF.WAL Write all bits 

TF .WBT Break-through write 

TF .XCC CTRL/C starts a command line interpreter command 
line (Command line characters are not sent to 
the task.) 

TF .XOF Send XOFF 


Table 2-4 lists subfunction bits that can be ORed with QIO functions. 
Additional details for using subfunction bits are included in Section 
Zedel. 


If a task invokes a subfunction bit that is not supported on the 
system, the subfunction bit is ignored, but the QIO request is not 
rejected. For example, if break-through write (TF.WBT) is not 
selected, an IO.WBT or IO.WLB!ITF.WBT function is interpreted as an 
IO.WLB function, 


The following example is a QIO request using more than one subfunction 
bit: a nonechoed (TF.RNE) read, terminated by a special terminator 
character (TF.RST) and preceded by a prompt. 


QIOSC IO.RPRITF.RNE!ITF.RST,...,<stadd,size,,pradd,prsize,vfc> 


2.3.2 Device-Specific QIO Functions 


Some device-specific functions described in this section are SYSGEN 
options. All except SF.GMC, IO.RPR, SF.SMC, IO.RTT, and I0.GTS can be 
issued by ORing a particular subfunction bit with another QIO 
function. These subfunction bits are specified in the following 
descriptions; subfunction bits are described in general in Section 
yee nega 


In addition to the device-specific QIO functions, this section also 
describes the use of subfunction bits TF.ESQ, TF.BIN, and TF.XOF. 
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Table 2-4 
Subfunction Bits - Summary 


TF.AST|TF.BIN|TF.CCO|TF.ESQ ITF TF.RAL|TF.RCU |TF.RNE|TF.RST|TF.TMO |TF.WAL |TF.WBT |TE.XCC |TF. XOF 
X X 
1 
2 3 
X X X 
2 2 2 
X 
3 X 
1 
X 1 
1 
3 3 
xX 3 


1. Exercise great care when uSing Read All and Read with Special Terminators together. Obscure problems can result. 


Allowed Subfunction Bits 


Equivalent 


Function | Subfunctions NOT 


STANDARD FUNCTIONS 


IO.ATT 
I0.DET 
IO.KIL 
IO.RLB 
I0.RVB 
IO.WLB 
IO.WVB 


DEVICE-SPECIFIC FUNCTIONS 


IO.ATA 
I0.CCcO 
SF.GMC 
I0.GTS 
I0O.RAL 
IO. RNE 
ITO.RPR 
IO.RST 
IO.RTT 
SF.SMC 
I0.WAL 
IO.WBT 


IO.ATT!TF.AST 
IO.WLB! TF.CCO 


IO.RLB! TF.RAL 
IO.RLB!TF.RNE 


IO.RLB! TF.RST 


IO.WLB! TF.WAL 
IO.WLB! TF.WBT 


2. These subfunctions are allowed but are not effective. They are stripped off when the read or write virtual operation is 
converted to a read or write logical operation. 


3. During a write-pass-all operation (IO.WAL or I0O.WLB!ITF.WAL) the terminal driver outputs characters without 
interpretation; it does not keep track of cursor position. 
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2.3.2.1 I0O.ATA - IO.ATA is a variation of the Attach function. The 
use of this function is eased by the addition of TF.NOT and TF.XCC 
subfunction bits, described later in this section. IO.ATA specifies 
asynchronous system traps (ASTs) to process unsolicited input 
characters. When called as follows: 


QIOSc IO.ATA,...,< [AST] , [PARAMETER2] [,AST2]> 


NOTE 


A minimum of one AST parameter (ast or 
ast2) is required. 


This function attaches the terminal and identifies "ast" and "ast2" as 
entry points for an unsolicited-input-character AST. Control passes 
to ast whenever an unsolicited character (other than CTRL/Q, CTRL/S, 
CTRL/X, or CTRL/O) is input. If the ast2 parameter is specified, an 
unsolicited CTRL/C character will result in entering the AST specified 
in that parameter. If ast2 is not specified, an unsolicited CTRL/C 
will result in entering the AST specified in the ast parameter. 


Unless the TF.XCC subfunction is specified, CTRL/C is trapped by the 
task and does not reach MCR. Thus, any task that uses IO.ATA without 
the TF.XCC subfunction should recognize some input Sequence as a 
request to terminate; otherwise, MCR cannot be invoked to abort the 
task in case of difficulty. 


Note that either ast2 or TF.XCC can be used, but not both in the same 
QIO request. If both are specified in the request, an IE.SPC error is 
returned. 


Upon entry to the AST routines, the unsolicited character and 
parameter 2 are in the top word on the stack, as shown below. That 
word must be removed from the stack before exiting the AST. 


SP+10 Event flag mask word 

SP+06 PS of task prior to AST 

SP+04 PC of task prior to AST 

SP+02 Task's directive status word 

SP+00 Unsolicited character in low byte; parameter 2, in the 


high byte, is a user-specified value that can be used 
to identify individual terminals in a multiterminal 
environment 


The processing of unsolicited input ASTs is eased through the use of 
TF.NOT and TF.XCC subfunction bits. When TF.XCC is included in the 
IO.ATA function, all characters (except CTRL/C) are handled in the 
manner previously described. CTRL/C marks the beginning of a command 
line interpreter (CLI) line that will be processed by a CLI task (for 
example, MCR); none of the characters, including the CTRL/C, are sent 
to the task issuing the function. 


When unsolicited terminal input (except CTRL/C) is received by the 
full-duplex terminal driver and the TF.NOT subfunction is used, the 
resulting AST serves only as notification of unsolicited terminal 
input; the terminal driver does not pass the character to the task. 
Upon entry to the AST service routine, the high byte of the first word 
on the stack identifies the terminal causing the AST (parameter 2). 
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After the AST has been effected, the AST becomes "disarmed" until a 
read request is issued by the task. If multiple characters are 
received before the read request is issued, they are stored in the 
type-ahead buffer. Once the read request is received, the contents of 
the type-ahead buffer, including the character causing the AST, is 
returned to the task; the AST is then "armed" again for new 
unsolicited input characters. Thus, using the TF.NOT subfunction 
allows a task to monitor more than one terminal for unsolicited input 
without the need to continuously read each terminal for possible 
unsolicited input. Note that the TF.NOT subfunction cannot be used 
with the CTRL/C AST; an unsolicited CTRL/C character flushes’ the 
type-ahead buffer. 


See the RSX-11M/11M-PLUS Executive Reference Manual for further 
details on ASTs. 


IO.ATA is equivalent to IO.ATT ORed with the subfunction bit TF.AST. 


2.3.2.2 IO.ATT!ITF.ESQ - The task issuing this function attaches a 
terminal and notifies the driver that it recognizes escape sequences 
input from that terminal. Escape sequences are recognized only for 
solicited input. (See Section 2.6 for a discussion of escape 
sequences.) 


If the terminal has not been declared capable of generating escape 
sequences, IO.ATTITF.ESQ has no effect other than attaching the 
terminal. No escape sequences are returned to the task because any 
ESC sent by the terminal acts as a line terminator. The SF.SMC 
function or the MCR SET /ESCSEQ command are used to declare the 
terminal capable of generating escape sequences (see Table 2-5 and 
Section 2.3.2.12). 


2.3.2.3 I10.CCO - This write function directs the driver to write to 
the terminal regardless of a CTRL/O condition that may be in effect. 
If CTRL/O is in effect, it is cancelled before the write is done. 


I0.CCO is equivalent to IO.WLB!TF.CCO. 


2.3.2.4 SF.GMC - The Get Multiple Characteristics function returns 
terminal characteristics information, as follows: 


QIOSC SF.GMC,...,<stadd,size> 


stadd 


The starting address of a data buffer of length "size" bytes. 
Each word in the buffer has the form 


-BYTE characteristic-name 
-BYTE 0 


characteristic-name 
One of the bit names given in Tabie 2-5. The value returned in 
the high byte of each byte-pair is 1 if the characteristic is 


true for the terminal and 0 if it is not true. 


For the TC.TTP characteristic (terminal type), one of the values shown 
in Table 2-6 is returned in the high byte. 
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Table 2-5 


Full-Duplex Terminal Driver-Terminal Characteristics 


for SF.GMC and SF.SMC Functions 


Bit Octal Corresponding 
Name Value Meaning (if asserted) MCR Command 


TC.ABD 77 
TC.ACR 24 
TC. ANI 122 


TC.ASPl 76 


TC.AVO 123 


TC.BIN 65 
TC.BLK 44 
TC.CTS 72 


TC.DEC 124 


TC.DLU4 4l 


TC.EDT 125 
TC.EPA 42 
TC.ESQ 35 

1 TCEFDX 64 


— fs Ty 


TC.HFL 13 


he 21 


TC. HLDL 44 


Auto-baud detection SET /ABAUD=TTnn: 
Wrap-around mode SET /WRAP=TTnn: 

ANSI CRT terminal 

Remote line answer speed SET /REMOTE=TTnn: speed 
VT100-family terminal display 

Binary input mode (read-pass-all) SET /RPA=TTnn: 

no characters are interpreted 


as control characters. 


Terminal is capable of block 
mode transfers 


Suspend output to terminal -- 
0 resume 
1 suspend 


Digital CRT terminal 

Dial-up line SET /REMOTE=TTnn: 
Terminal performs editing functions 

When TC.PAR is enabled: -- 


O=odd parity 
l=even parity 


Input escape sequence SET /ESCSEQ=TTnn: 
recognition 

Full-duplex mode SET /FDX=TTnn: 
Hardware form-feed capability SET /FORMFEED=TTnn: 


(If 0, form-feeds are simulated 
using TC.LPP.) 


Number of fill characters to SET /HFILL=TTnn:x 
insert after a carriage return (0-7=x) 
(Use a value of 7 for the LA30-S.) 


Horizontal tab capability (if 0, SET /HHT=TTnn: 
horizontal tabs are simulated using 

spaces.) 

Hold screen mode SET /HOLD=TTnn: 


Subline on interface (=0-15) (Read only) -- 


; Page length (1-255.=x) LINES=TTnn :x 


(continued on next page) 
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Table 2-5 (Cont.) 
Full-Duplex Terminal Driver-Terminal Characteristics 
for SF.GMC and SF.SMC Functions 


Corresponding 
Meaning (if asserted) MCR Command 


Broadcast disabled 


TC.NBR 


SET /NOBRO=TTnn: 


TC.NEC | 47 Echo suppressed SET /ECHO=TTnn: 
| 
TC.PAR 41 Generate and check parity -- 
TC.PRI 51 Terminal is privileged (Read only) SET /PRIV=TTnn: 
lc. RAT | 7 Type-ahead buffer: SET /TYPEAHEAD=TTnn: 
0 = l-character type-ahead 
1 = 36-character type-ahead 
| (RSX-11M only) | 
TC.RGS 126 Terminal supports REGIS -- 
instructions 
TC.RSP2 3 Receiver speed (bits-per-second) SET /SPEED=TTnn:rev:xmit 
C.SCP 12 Terminal is a scope (CRT) SET /CRT=TTnn: 
TC.SLV 50 Terminal is a slave SET /SLAVE=TTnn: 
C.SMR 25 Upper-case conversion disabled SET /LOWER=TTnn: 
TC.TBF 71 Type-ahead buffer count (read), -~ 
or flush (write) 
TC.TBS 100 Type-ahead buffer size (0-255=x) SET /TYPEAHEAD=TTnn :x 
(RSX-11MPLUS only) 
TC.TBM 101 Type-ahead buffer mode -- 
O=task typeahead 
1=CLI typeahead 
(RSX-11M-PLUS only) 
“| TC. TTP 10 Terminal type (=0-255.=x) SET /X=TTnn: 
SET /TERM=TTnn:x 
TC.VFL 14 Send four fill characters after SET /VFILL=TTnn: 
line feed 
TC.WID3 1 Page width (=1-255.=x) SET /BUF=TTnn:x 
TC.XSP2 4 Transmitter speed (bits-per-second) SET /SPEED=TTnn:rev:ixmit 
“TC. 8BC 67 Pass eight bits on input, even SET /EBC=TTnn: 
if not binary input mode 
(TC.BIN) 
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1. Effective for VT5x and VT61 only. 
2. TC.RSP, TC.XSP, TC.ASP and corresponding MCR SET /SPEED and SET /REMOTE 


command values for terminal receiver and transmitter speeds are listed below. 
(The valid combinations for each interface are in the RSX-11M/M-PLUS MCR 


Operations Manual.) 


NOTE 


The MCR SET /SPEED command requires parameters for both receiver (rcv) 
and transmitter (xmit) baud rates, as follows: 


SET /SPEED=TTnn:rev:xmit 


TC.ASP 
TC.RSP or 
TC.XSP Actual baud rate (in bps) 
value and valid MCR SET /SPEED or SET /REMOTE 
values 
s.0 (disabled) 
S.50 50 (Baudot codes are not 
supported) 
8.75 75 
$.110 110 
$.134 134 
§.150 150 
$.200 200 
§.300 300 
§.600 600 
§.1200 1200 
S§.1800 1800 
S$.2000 2000 
S.2400 2400 
$.3600 3600 
§.4800 4800 
S.7200 7200 
S§.9600 9600 
S.EXTA (DH11 external speed A) 
S.EXTB (DH11 external speed B) 
§.19.2 19200 
NOTE 


Speed can be set only on DH11 and D211 controllers. DZ11 transmitter and 
receiver speeds must be equal (no split baud rates permitted). Only one 
value may be specified for the remote answer speed. This value applies 
to both the transmitter and receiver. 


3. Unsolicited input that fills the buffer before a terminator is received is 
likely invalid. When this happens, the driver discards the input by simulating 
a CTRL/U and echoing “U. 


4. A program can enable the auto-call feature of the DFO3 modem by setting 
TC.DLU to a value of two. (This is in addition to receiving incoming calls.) 
While in this mode, read and write requests are serviced even when a line is not 
in use. Consequently, I/0 requests will not fail when the line is hung-up, 
which is the case for remote lines (TC.DLU=1). 
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The TC.TTP characteristic, when read by the terminal driver, sets 
implicit values for terminal characteristics TC.LPP, TC.WID, TC.HFF, 
TC.HHT, TC.VFL, and TC.SCP as shown in Table 2-6. These values can be 
changed (overridden) by subsequent Set Multiple Characteristics 
requests. In addition, TC.TTP is used by the terminal driver to 
determine cursor positioning commands, aS appropriate. 


Table 2-6 
Bit TC.TTP (Terminal Type) Values Set by SF.SMC 
and Returned by SF.GMC 


Implicit Characteristics? 


Terminal | 

Symbolic | type ii HH TC.VFL | TC.SCP 
0 T.UNKO Unknown 
1 T.AS33 ASR33 1 
2 | T.KS33 KSR33 66 72 i 
3 T.AS35 ASR35 66 72 1 
4 T.L30S LA30S 66 80 7 
5 T.L30P LA30P 66 80 
6 T.LA36 LA36 66 132 
7 T.VTO5 VT05 20 72 1 1 1 
10 T.VT50 vVT5S0 12 80 1 1 
11 T.VT52 vT52 24 80 1 1 
12 T.VT55 vT55 24 80 1 1 
13 T.VT6l vT6l 24 80 1 1 
14 T.L180 LA180S 66 132 1 
15 T.V100 VT100 24 80 1 1 
16 T.L120 LA120 66 132 1 
20 T.LA12 LA12 66 132 1 1 
21 T.L1O00O LA100 66 132 1 1 
22 T.LA34 LA34 66 132 1 
23 T.LA38 LA38 66 132 1 
24 T.V101 VT101 24 80 1 1 
25 T.V102 VT102 24 80 1 1 
26 T.V105 VT105 24 80 1 1 
27 T.V125 VT125 24 80 1 1 
30 T.V131 VT131 24 80 1 1 
31 T.V132 VT132 24 80 1 1 
32 T.LA50 LASO 60 80 1 1 
33 T.LOP1 LOPO1] 66 132 1 1 
34 T.LQP2 LQPO2 66 132 1 1 


1.0ctal values 0-177 are reserved by DIGITAL. Values 200-377 are available for 
customer use to define non-DIGITAL terminals. 


2.-Implicit characteristics are shown as supported by the driver. Values not shown 
are not automatically set by the driver. An "unknown" terminal type has no 
implicit characteristics. 


The TC.CTS characteristic returns the present suspend (CTRL/S), resume 
(CTRL/Q), or suppress (CTRL/O) state set via the SF.SMC function. 
Values returned are as follows: 


Value 
Returned State 
0 Resume (CTRL/Q) 
l Suspend (CTRL/S) 
2 Suppress (CTRL/O) 
3 Both suppress and suspend 
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When a value of 0 is used with the SF.SMC function, the suspend state 
is cleared; a value of 1 selects the suspend state. 


The TC.TBF characteristic returns the number of unprocessed characters 
in the type-ahead buffer for the specified terminal. This allows 
tasks to determine if any characters were typed that did not require 
AST processing. In addition, the value returned can be used to read 
the exact number of characters typed, rather than a typical value of 
80. or 132. characters for the terminal. 


NOTES 


l. It is necessary that the task attach 
' the terminal to receive characters 
from the type-ahead buffer. 


2. The maximum capacity of the 
type-ahead buffer is 36. characters 
for RSX-11M systems and 255. 
characters for RSX-11M-PLUS systems. 


3. Using TC.TBF in an SF.SMC function 
will flush the type-ahead buffer. 


2.3.2.5 I0.GTS - This function is a Get Terminal Support request that 
returns information to a 4-word buffer specifying which SYSGEN-option 
features are part of the terminal driver. Only two of these words are 
currently defined. Table 2-7 gives details for these words. The 
I0.GTS function is a SYSGEN option. If I0.GTS is issued on a_ system 
without IO.GTS support, IE.IFC is returned in the I/O status block. 


The various symbols used by the I0.GTS, SF.GMC, and SF.SMC functions 
are defined in a system module, TTSYM. These symbols include: Fl.xxx 
and F2.xxx (Table 2-7); T.xxxx (Table 2-6); TC.xxx (Table 2-5); and 
the SE.xxx error returns described in Table 2-8, Section 2.4. These 
symbols may be defined locally within a code module by using: 


-MCALL TTSYMS 


TTSYMS 


Symbols that are not defined locally are automatically defined by the 
Task Builder. 


Octal values shown for the symbols are subject to change. Therefore, 
it is recommended that only the symbolic names be used. 
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Table 2-7 
Information Returned by Get Terminal Support (1I0.GTS) QIO 


Mnemonic Meaning When Set to l 


Word OOF Butter: 


0 1 F1.ACR Automatic CR/LF on long lines 
1 2 F1.BTwt Break-through write 
2 4 F1.BUF Checkpointing during terminal input 
3 10 Fl.ural Unsolicited-input-character AST 
4 20 PiLecCo. Cancel CTRL/O before writing 
5 40 F1.ESQl Recognize escape sequences in solicited 
input 
100 F1.HLD Hold-screen mode 
200 F1.Lwcl Lower- to uppercase conversion 
F1.RNE Read with no echo 
F1.RPRL Read after prompting 
10 2000 F1.RST Read with special terminators 
sia 4000 F1.RUBL | CRT rubout 
12 10000 F1.SYN CTRL/R terminal synchronization 


14 40000 F1.UTB Input characters buffered in task's 
address space 


15 100000 Fl..sVBE Variable-length terminal buffers 


Word 1 of Buffer: 


| 

| 6 
7 
8 400 
2 1000 


13 20000 Fl. TRW Read all and write all 


0 F2.SCH! | Set characteristics QIO (SF.SMC) 
1 F2.GCH! | Get characteristics QI0 (SF.GMC) 
5 F2.SFF Formfeed can be simulated 

6 F2.cup! | cursor positioning 

7 F2.,FDX Full Duplex Terminal Driver 


1. SYSGEN options on RSX-11M systems. 


2.3.2.6 I0O.RAL - The Read All function causes the driver to pass all 
bits to the requesting task. The driver does not intercept control 
characters or mask out the "parity" (high-order) bit. For example, 
CTRL/C, CTRL/Q, CTRL/S, CTRL/O, and CTRL/Z are passed to the program 
and are not interpreted by the driver. 


NOTE 


IO.RAL echoes the characters that are 
read. The terminal driver in Version 2 
of RSX-11M did not echo a Read All. To 
read all bits without echoing, use 
IO.RAL!ITEF.RNE. 


IO.RAL is equivalent to IO.RLB ORed with the subfunction bit MTF.RAL. 
The IO.RAL function can be terminated only by a full character count 
(input buffer full). 
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2.3.2.7 I0O.RNE - The IO.RNE function reads terminal input characters 
without echoing the characters back to the terminal for immediate 
display. This feature can be used when typing sensitive information 
(for example, a password or combination) or when reading a badge with 
the RTO2-C terminal. 


(Note that the no-echo mode can also be selected with the SF.SMC 
function; see Table 2-5, bit TC.NEC.) 


CTRL/R is ignored while an IO.RNE is in progress. 


The IO.RNE function is equivalent to IO.RLB ORed with the subfunction 
bit TF.RNE. 


2.3.2.8 IO.RPR - The IO.RPR Read After Prompt functions as an _ IO.WLB 
(to write a prompt to the terminal) followed by IO.RLB. However, 
IO.RPR differs from this combination of functions as follows: 


e System overhead is lower with the IO.RPR because only one QIO 
is processed. 


e When using the IO.RPR function, there is no "window" during 
which a response to the prompt may be ignored. Such a window 
occurs if IO.WAL/IO.RLB is used, because no read may be posted 
at the time the response is received. 


e If the issuing task is checkpointable, it can be checkpointed 
during both the prompt and the read requested by the IO.RPR. 


e A CTRL/O that may be in effect prior to issuing the IO.RPR is 
canceled before the prompt is written. 


Subfunction bits may be ORed with IO.RPR to write the prompt as a 
Write All (TF.BIN) and to send xXOFF after the read (TF.XOF). In 
addition, read subfunction bits TF.RAL, TF.RNE, and TF.RST can be used 
with IO.RPR. 


NOTE 


If an IO.RPR function is in progress 
when the driver receives a CTRL/R or 
CTRL/U, the prompt is redisplayed. 


2.3.2.9 IO.RPRITE.BIN - This function results in a read after a 
"binary" prompt; that is, a prompt is written by the driver with no 
character interpretation (as if it were issued as an IO.WAL). 


2.3.2.10 IO.RPRITE.XOF - This function causes the driver to send an 
XOFF to the terminal after its prompt-and-read. The XOFF or CTRL/S 
may have the effect of inhibiting input from the terminal, if the 
terminal recognizes XOFF for this purpose. TF.XOF is ignored when 
fuli-duplex I/0 is in use. 


FULL-DUPLEX TERMINAL DRIVER 


2.3.2.11 I0O.RST - This function is similar to an I0.RLB, except 
certain special characters terminate the read. These characters are 
in the ranges 0-037 and 175-177. The driver does not interpret the 
terminating character, with certain exceptions.l For example, a 
horizontal TAB (011) is not expanded, a RUBOUT (or DEL, 177) does not 
erase, and a CTRL/C does not produce an MCR prompt. 


Upon successful completion of an I0.RST request that was not 
terminated by filling the input buffer, the first word of the I/0 
status block contains the terminating character in the high byte and 
the IS.SUC status code in the low byte. The second word contains the 
number of bytes contained in a buffer. The terminating character is 
not put in the buffer. 


IO.RST is equivalent to IO.RLBITF.RST. 


2.3.2.12 SF.SMC - This function enables a task to set and reset’ the 
characteristics of a terminal. Set Multiple Characteristics is the 
inverse function of SF.GMC. Like SF.GMC, it is called in the 
following way: 


OIOSC SF.SMC,...,<stadd,size> 


stadd 


The starting address of a buffer of length "size" bytes. Each 
word in the buffer has the form 


-BYTE characteristic-—name 
~-BYTE value 


characteristic-—name 
One of the symbolic bit names given in Table 2-5. 

value 
Either 0 (to clear a given characteristic) or 1 (to set a 
characteristic). 

Table 2-5 notes the restrictions that apply to these characteristics. 


If the characteristic-name is TC.TTP (terminal type), value can have 
any of the values listed in Table 2-6. 


A nonprivileged task can only issue an SF.SMC request for its own 
terminal (TI:). A privileged task can issue SF.SMC to any terminal. 


Terminal output can be suspended or resumed (Simulated CTRL/S and 
CTRL/Q, respectively) by specifying an appropriate value for TC.CTS. 
A value of O resumes output and a value of 1 suspends output. 


1. If upper- to lowercase conversion is disabled, characters 175 and 
176 do not act as terminators. CTRL/O, CTRL/Q, and CTRL/S (017, O21, 
and 023, respectively) are not special terminators. The driver 
interprets them as output control characters in a normal manner. 
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Specifying any value for TC.TBF flushes (clears) the type-ahead buffer 
(forces the type-ahead buffer count to 0). 


2.3.2.13 I0O.RTT - This QIO function reads characters in a manner like 
the I0O.RLB function, except a user-specified character terminates the 
read operation. The specified character's code can range from 0-377. 
It is user designated by setting the appropriate bit in a 16-word 
table that corresponds to the desired character. Multiple characters 
can be specified by setting their corresponding bits. 


The 16-word table starts at the address specified by the table 
parameter. The first word contains bits that represent the first 16 
ASCII character codes (0-17); similarly, the second word contains 
bits that represent the next 16 character codes (20-37), and so forth, 
through the sixteenth word, bit 15, which represents character code 
ce A gs For example, to specify the % symbol (code 045) as a read 
terminator character, set bit 05 in the third word, since the _ third 
word of the table contains bits representing character codes 40-57. 


If the CTRL/S (023), CTRL/Q (021), and/or any characters whose codes 
are greater than 177 is/are desired as the terminator character(s), 
the terminal must be set to read-pass~-all operation (TC.BIN=1), or 
read-pass 8-bits (TC.8BC), as listed in Table 2-5. 


The optional time-out count parameter can be included, as desired. 


2.3.2.14 IO.WAL - The Write All function causes the driver to pass 
all output from the buffer without interpretation. It does not 
intercept control characters. Long lines are not wrapped around if 
input/output wrap-around has been selected. 


IO.WAL is equivalent to the IO.WLB!ITF.WAL function. 


2.3.2.15 IO.WBT - The IO.WBT function instructs the driver to write 
the buffer regardless of the I/O status of the receiving terminal. If 
an IO.WBT function is issued on a system that does not support IO.WBT, 
it is treated as an IO.WLB function. 


e If another write function is currently in progress, it 
finishes the current request and the IO.WBT is the next write 
issued. The effect of this is that a CTRL/S can stop IC.WBT 
functions. Therefore, it may be desirable for tasks to time 
out on IO.WBT operations. 


e If a read is currently posted, the IO.WBT proceeds, and an 
automatic CTRL/R is performed to redisplay any input that was 
received before the break-through write was effected (if the 
terminal is not in the full-duplex mode). 

e cCTRL/O, if in effect, is canceled. 


@e An escape sequence that was interrupted is rubbed out. 


An IO.WBT function cannot break through another I0.WBT that is in 
progress. 


Break-through write may only be issued by a privileged task. The 
privileged MCR command BRO (broadcast) uses IO.WBT. 
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2.3.2.-16 IO.HNG - The IO.HNG function disconnects a terminal that is 
on a remote line. This function has no arguments. 


A nonprivileged task can only issue an IO.HNG request for its own 
terminal (TI:). A privileged task can issue IO.HNG to any terminal. 


2.4 STATUS RETURNS 


Table 2-8 lists error and status conditions that are returned by the 
terminal driver to the I/O status block. 


Most RSX-11M error and status codes returned are byte values. For 
example, the value for IS.SUC is 1. However, IS.CC, IS.CR, IS.ESC, 
and IS.ESQ are word values. When any of these codes are returned, the 
low byte indicates successful completion, and the high byte shows what 
type of completion occurred. 


To test for one of these word-value return codes, first test the low 
byte of the first word of the I/O status block for the value IS.SUC. 
Then, test the full word for IS.CC, IS.CR, IS.ESC, or IS.ESQ. (If the 
fuli word tests equal to IS.SUC, then its high byte is 0, indicating 
byte-count termination of the read.) 


The "error" return IE.EOF may be considered a successful read _ since 
characters returned to the task's buffer can be terminated by a CTRL/Z 
character. 


The SE.xxx codes are returned by the SF.GMC and SF.SMC functions as 
described in Sections 2.3.2.4 and 2.3.2.12. When any of these codes 
are returned, the low byte in the first word in the I/O status’ block 
will contain IE.ABO. The second I0OSB word contains an offset 
(starting from 0) to the byte in error in the QIO's stadd buffer. 


Table 2-8 
Terminal Status Returns 


IE.EOF Successful completion on a read with end-of-file 


The line of input read from the terminal was 
terminated with the end-of-file character CTRL/Z. 
The second word of the I/O status block contains’ the 
number of bytes read before CTRL/Z was seen. The 
input buffer contains those bytes. 


IS.SUC Successful completion 


The operation specified in the QIO directive was 
completed successfully. If the operation involved 
reading or writing, you can examine the second word 
of the I/O status block to determine the number of 
| bytes processed. The input buffer contains’ those 


| | bytes. | 


IS.TMO 


IE.ABO 


IS.CR 

IS.ESC 
IS.ESQ 
IS. PND 


TE.BAD 


IE.BCC 
| 
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Table 2-8 (Cont.) 
Terminal Status Returns 


Successful completion on a read 


The line of input read from the terminal was 
terminated by a CTRL/C. The input buffer contains 
the bytes read. 


Successful completion on a read 


The line of input read from the terminal was 
terminated by a carriage return. The input buffer 
contains the bytes read. 


Successful completion on a read 


The line of input read from the terminal was 
terminated by an Altmode character. The input buffer 
contains the bytes read. 


Successful completion on a read 


The line of input read from the terminal was 
terminated by an escape sequence. The input buffer 
contains the bytes read and the escape sequence. 


I/O request pending 


The operation specified in the QIO directive has not 
yet been executed. The I/O status block is filled 
with Os. 


Successful completion on a read 


The line of input read from the terminal was 
terminated by a time-out (TF.TMO was set and the 
specified time interval was exceeded). The input 
buffer contains the bytes read. 


Operation aborted 


The specified I/O operation was cancelled by I0.KIL 
while in progress or while in the I/O queue. The 
second word of the I/O status block indicates’ the 
number of bytes that were put in the buffer before 
the kill was effected. 


Bad parameter 

The size of the buffer exceeds 8128 bytes. 

Framing error 

A framing error was hardware-detected and returned by 
the controller. All characters up to (but not 
including) the erroneous character are in the buffer. 
This condition can result by pressing the BREAK key 


on some terminals, or by hardware problems. 


(continued on next page) 


IE.DAA 


IE.DAO 


TE.DNA 


IE.DNR 


IE.IES 


LE. TEC 
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Table 2-8 (Cont.) 
Terminal Status Returns 


Reason 
Device already attached 


The physical device unit specified in an _ I0.ATT 
function was already attached by the issuing task. 
This code indicates that the issuing task has already 
attached the desired physical device unit, not that 
the unit was attached by another task. If the attach 
specified TF.AST or TF.ESQ, these subfunction bits 
have no effect. 


Data overrun error 


A data overrun error was hardware-detected and 


returned by the controller. All characters up to 
(but not including) the erroneous character are _ in 
the buffer. This error occurs when a hardware 


failure or incompatibility causes characters to be 
received by the controller faster than they can be 
processed (that is, an incorrect serial I/O baud rate 
or format exists). 


Device not attached 


The physical device unit specified in an _ I0.DET 
function was not attached by the issuing task. This 
code has no bearing on the attachment status of other 
tasks. 


Device not ready 


The physical device unit specified in the QIO 
directive was not ready to perform the desired I/0 
operation. This code is returned to indicate one of 
the following conditions: 


e A time-out occurred on the physical device unit 
(that is, an interrupt was lost). 


e An attempt was made to perform a function on a 
remote DH11 or DZ11 line without carrier present. 


Invalid escape sequence 

An eScape sequence was started but escape-sequence 
syntax was violated before the sequence was 
completed. (See Section 2.6.4.) The character 
causing the violation is the last character in the 
buffer. 

Tllegal function 


A function code specified in an I/O request was 


illegal for terminals; or, the function code 
specified was a SYSGEN option not selected for this 


system. 


(continued on next page) 
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Table 2-8 (Cont.) 
Terminal Status Returns 


Reason 
Buffer allocation failure 


System dynamic storage has been depleted resulting in 
insufficient space available to allocate an 
intermediate buffer for an input request or an AST 
block for an attach request. 


Device off line 


The physical device unit associated with the LUN 
specified in the QIO directive was not on line. When 
the system was booted, a device check indicated that 
this physical device unit was not in the 
configuration. In RSX-11M-PLUS systems, the physical 
device unit could have been configured off line. 


Partial escape sequence 


An escape sequence was started, but read-buffer space 
was exhausted before the sequence was completed. See 
Section 2.6.4.3. 


Privilege violation 


In a multiuser system, a nonprivileged task issued an 
IO.WBT, directed an SF.SMC to a terminal other than 
TI:, or it attempted to set its privilege bit. 


Illegal address space 


The buffer specified for a read or write request was 
partially or totally outside the address space of the 
issuing task, a byte count of 0 was specified, or an 
odd or O AST address was specified. 


Character parity error 


A parity error was hardware~-detected and returned by 
the controller. All characters up to (but not 
including) the erroneous character are in the buffer. 


A terminal characteristic other than those in Table 
2-5 was named in an SF.GMC or SF.SMC request, or a 
task attempted to assert TC.PRI. 


An attempt was made to change a fixed characteristic 
in a SF.SMC subfunction request (for example, an 
attempt was made to change the unit number). 


The new value specified in an SF.SMC request for’ the 
TC.TTP terminal characteristic was not one of those 
listed in Table 2-6. 
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Table 2-8 (Cont.) 
Terminal Status Returns 


SE.NSC An attempt was made _ to change a nonsettable 
characteristic. This error can occur when an attempt 
is made to make a local-only line a remote line when 
the controller does not support remote lines, or when 
no remote line support was specified during SYSGEN. 

SE.SPD The new speed specified in an SF.SMC_ subfunction 
request was not valid for the controller associated 
with the specified terminal. 


2.5 CONTROL CHARACTERS AND SPECIAL KEYS 


This section describes the meanings of special terminal control 
characters and keys for RSX-11M. Note that the driver does not 
recognize control characters and special keys during a Read All 
request (IO.RAL), and recognizes only some of them during a Read with 
Special Terminators (I0.RST). 


2.5.1 Control Characters 


A control character is input from a terminal by holding the control 
key (CTRL) down while typing one other key. Three of the control 
characters described in Table 2-9, CTRL/R, CTRL/U, and CTRL/Z, are 
echoed on the terminal as “R, “U, and “Z, respectively. 


Table 2-9 
Terminal Control Characters 


Typing CTRL/C causes unsolicited input on that 
terminal to be directed to a control line interpreter 
task, such as MCR. (Command line interpreters are 
invoked and display a prompt in a manner similar to 
that of MCR; therefore, for the purposes of this 
discussion, it is assumed that MCR is the command 
line interpreter in use, although the terminal driver 
will respond to other command line interpreters ina 
similar manner.) The "MCR>" prompt is echoed when the 
terminal driver is ready to accept an unsolicited MCR 
command line for input. When the unsolicited input 
is terminated, the command line is passed to MCR. 


CTRE/© 


If the last character typed on the terminal was a 
CTRL/S (suspend output), CTRL/C restarts suspended 
output and directs subsequent input to MCR. 


old-screen mode SY 
selected and the terminal 


hold-screen mode, typing a 
terminal from hold-screen mode. 


EN ovtion has been | 


G 
s a VT5x or VT6l1 in 
CTRL/C removes the 


(continued on next page) 
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CTRL/J 
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CTRL/L 


CTRL/M 


CTRL/O 


CTRL/Q 
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Table 2-9 (Cont.) 
Terminal Control Characters 


CTRL/C characters can also be directed to a task if 
the task has attached a terminal and has specified an 
unsolicited-input-character AST (see Section 
26 Se eel) CTRL/C characters are also passed to a 
task if an IO.RAL or IO.RST function is effected. 


NOTE 


If the terminal driver receives a CTRL/C 
character during a read operation (except 
during a Read-Pass-All operation or a_e Read 
With Special Terminators operation), the read 
operation is terminated, the type-ahead 
buffer is cleared, and an IS.CC status code 
is returned to the task. 


CTRL/I or TAB characters initiate a horizontal tab, 
and the terminal spaces to the next tab stop. Tabs 
at every eighth character position are simulated by 
the terminal driver. 


CTRL/J is equivalent to a LINE FEED character. 


CTRL/K initiates a vertical tab, and the terminal 
tabs to the next vertical tab stop. For a CRT 
terminal, four LINE FEEDS are output. 


CTRL/L initiates a formfeed. If the terminal has 
hardware formfeed support, the driver echos “L. 
Otherwise, the driver simulates the formfeed by 
outputting enough LINE FEED characters to advance the 
next character position to the top of the next page. 
If a CRT terminal is in use, four LINE FEEDs are 
output. 


CTRL/M is equivalent to a carriage RETURN character 
(see Section 2.5.2). 


CTRL/O suppresses terminal output. For attached 
terminals, CTRL/O remains in effect (output is 
suppressed) until one of the following occurs: 

e The terminal is detached. 

e Another CTRL/O character is typed. 

e An I0.CCO or IO.WBT function is issued. 

e Input is entered. 

For unattached terminals, CTRL/O suppresses output 
for only the current output buffer (typically one 


line). 


CTRL/Q resumes terminal output previously suspended 
by means of CTRL/S. 


| 
| 
| 


ee es 
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Table 2-9 (Cont.) 
Terminal Control Characters 


Character | Meaning 


CTRL/S CTRL/S suspends terminal output. (Output can be 
resumed by typing CTRL/Q or CTRL/C.) 


CTRL/R CTRL/R response is a terminal driver feature that can | 
be selected during RSX-11M V3.2 SYSGEN. Typing 

CTRL/R results in a carriage return and line _ feed 
being echoed, followed by the incomplete 
(unprocessed) input line. Any tabs that were input 
are expanded and the effect of any rubouts is shown. 
On hardcopy terminals, CTRL/R allows verifying the | 
effect of tabs and/or rubouts in an input line. 
CTRL/R is also useful for CRT terminals when the CRT | 
rubout SYSGEN option has been selected (see Section 
2.8). For example, after rubbing out the left-most 
character on the second displayed line of a wrapped 
input line, the cursor does not move to the right of 
the first displayed line. In this case, CTRL/R 
brings the input line and the cursor back together 


again. 

CTRL/U Typing CTRL/U before typing a line terminator deletes 
previously typed characters back to the beginning of 
the line. The system echoes this character as “U 
followed by a carriage return and a line feed. 

CTRL/X This character clears the type-ahead buffer. 

CTRL/Z CTRL/Z indicates an end-of-file for the current 


| terminal input. It signals MAC, PIP, TKB, and other 
system tasks that terminal input is complete, 
allowing the task to exit. The system echoes this 
character as “Z, followed by a carriage return and a 


line feed. 


2.5.2 Special Keys 


The ESCape, carriage RETURN, and RUBOUT keys have special significance 
for terminal input, as described in Table 2-10. A line can be 
terminated by an ESCape (or Altmode), carriage RETURN, or CTRL/Z 
characters, or by completely filling the input buffer (that is, by 
exhausting the byte count before a line terminator is typed). The 
standard buffer size for a terminal can be determined for a task by 
issuing a Get LUN Information system directive and examining Word 5 of 
the buffer. An operator can obtain the same information with the MCR 
SET /BUF=TI: command. 


2.6 ESCAPE SEQUENCES 


Escape sequences are strings of two or more characters beginning with 
an ESC (033) character. In RSX-11M systems, escape sequence support 
described in this section is’ a SYSGEN option. Some terminals generate 
an escape sequence when a special key is pressed (for example, the FCN 
key on the VT61). On any terminal, an escape sequence may be 
generated manually by typing ESCape followed by the appropriate 
characters. 
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Escape sequences provide a way to pass input to a task without 
interpretation by the operating system. This could be done with a 
number l-character Read All functions, but escape sequences allow them 
to be read with IO.RLB requests. 


Table 2-10 
Special Terminal Keys 


ec me ag Ae oe ea SE tg eee a Oe ee 
Meaning 


ESCape If escape sequences are not recognized, typing ESCape 
or Altmode signals the terminal driver that there is 
no further input on the current line. This line 
terminator allows further input on the same line, 
because the carriage or cursor is not returned to the 
first column poSition. 


If escape sequences are recognized, ESCape signals 
the beginning of an escape sequence. (See Section 
2.6.) 


RETURN Typing RETURN terminates the current line and causes 
the carriage or cursor to return to the first column 
on the line. 


RUBOUT Typing RUBOUT deletes the last character typed on an 
input line. Only characters typed since the last 
line terminator may be deleted. Several characters 
can be deleted in sequence by typing successive 
RUBOUTS. 


For example, on a printing terminal, the first RUBOUT 
echoes a backslash (\) followed by the character that 
has been deleted, even if the terminal is in the 
no-echo mode. Subsequent RUBOUTS cause only the 
deleted character to be echoed. The next character | 
typed that is not a RUBOUT causes another backslash 
to be printed, followed by the new character. The 
non-RUBOUT character will not be echoed if the 


terminal is in the no-echo mode; however, a 
backslash is echoed in response to the first 
non-RUBOUT character. The following example 


illustrates rubbing out ABC and then typing CBA: 
ABC\CBA\CBA 


The second backslash is not displayed if a line 
| terminator is typed after rubbing out the characters | 
| | on a line, as in the following example: 
| | 


ABC\CBA 
At SYSGEN time, the "CRT rubout" feature can _ be 


selected. This feature applies to a terminal only 
after a SET MCR directive has been issued: 


| SET /CRT=TI: 


(continued on next page) 
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Table 2-10 (Cont.) 
Special Terminal Keys 


Meaning 


If the CRT rubout feature was selected, RUBOUT causes 
the last typed character (if any) to be removed from 
the incomplete input line and a 
backspace-space-backspace sequence of characters for 
that terminal are echoed. If the last typed 
character was a tab, enough backspaces are issued to 
move the cursor to the character position before the 
tab was typed. Tf a long input line was split, or 
"wrapped," by the automatic-carriage-return option, 
and a RUBOUT erases the last character of a previous 
| line, the cursor is not moved to the previous line. 
CTRL/R must be used to resynchronize the current, 
display with the contents of the incomplete input 
line. 


2.6.1 Definition 


The format of an escape sequence as defined in American National 
Standard X 3.41-- 1974 and used in the VT100 is: 


ESC ees F 


ESC 


The introducer control character (33(8)) that is named escape. 


The intermediate bit combinations that may or may not be 
present. I characters are bit combination 40(8) to 57(8) 
inclusive in both 7- and 8-bit environments. 


The final character. F characters are bit combinations 60(8) 
to 176(8) inclusive in escape sequences in both 7- and 8-bit 
environments. 


The occurrence of characters in the inclusive ranges 0(8) to 37(8) 
is technically an error condition whose recovery is to execute 
immediately the function specified by the character and then 
continue with the escape sequence execution. The exceptions are: 
if the character ESC occurs, the current escape sequence is aborted, 
and a new one commences, beginning with the ESC just received; if 
the character CAN (30(8)) or the character SUB (32(8)) occurs, the 
current escape sequence is aborted, as is the case with any control 
character. 


There are five exceptions to this general definition; these 
exceptions are discussed in Section 2.6.5. 
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2.6.2 Prerequisites 


Two prerequisites must be satisfied before escape sequences can be 
received by a task. 


First, the task must "ask" for them by issuing an I0O.ATT function 
and invoking the subfunction bit TF.ESQ. 


Second, the terminal must be declared capable of generating escape 
sequences. This may be done with an MCR SET command: 


SET /ESCSEQ=TI: 


An alternative way to tell the driver that the terminal can generate 
escape sequences is by issuing the Set Multiple Characteristics 
request. (See Section 2.3.2.12). 


If either of these prerequisites is not satisfied, the ESC character 
is treated as a line terminator. 


If both prerequisites are satisfied, CTRL/SHIFT/O (037) may be used as 
an Altmode character.l! This character does not act as an Altmode from 
a terminal that cannot generate eScape Sequences. 


2.6.3 Characteristics 


Escape sequences always act as line terminators. That is, an input 
buffer may contain other characters that are not part of an escape 
sequence, but an escape sequence always comprises the last characters 
in the buffer. 


Escape sequences are not echoed. However, if a non-CRT rubout 
sequence is in progress, it is closed with a backslash when an escape 
sequence is begun. 


Escape sequences are not recognized in unsolicited input streams. 
Neither are they recognized in a Read with Special Terminators 
(subfunction bit TF.RST) nor in a Read All (subfunction bit TF.RAL). 


2.6.4 Escape Sequence Syntax Violations 


A violation of the syntax defined in Section 2.6.1 causes the driver 
to abandon the escape sequence and to return an error (IE.IES). 


2.6.4.1 DEL or RUBOUT (177) - The character DEL or RUBOUT is not 
legal within an escape sequence. Typing it at any point within an 
escape sequence causes the entire sequence to be abandoned and deleted 
from the input buffer. Thus, use DEL or RUBOUT to abandon an escape 
sequence, if desired, once you have begun it. 


1. An Altmode is a line terminator that does not cause the cursor to 


advance to a new line. On terminals that cannot generate escape 
sequences, the ESCape key acts as an Altmode. Characters 175 and 176 
also function as ltmodes if the terminal has not been deciared 


lowercase (MCR command SET /LOWER). 
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2.6.4.2 Control Characters (0-037) - The reception of any character 
in the range 0 to 037 (with four exceptions -- see footnotel) is a 
syntax violation that terminates the read with an error (IE.IES). 


2.6.4.3 Full Buffer - A syntax error results when an escape sequence 
is terminated by running out of read-buffer space, rather than by 
receipt of a final character. The error IE.PES is returned. For 
example, after a task issues an IO.RLB with a buffer length of 2, and 


you type: 
ESC ! A 


the buffer contains "ESC !", and the I/O status block contains: 


IOSB IE.PES 


2 


| ee | 


The "A" is treated as unsolicited input. 


2.6.5 Exceptions to Escape-Sequence Syntax 


Five "final characters" that normally terminate an escape sequence are 
treated aS special cases by the terminal driver for use with certain 
terminals: 


BoC Ties 
ESC 0... 
ESC P... 
ESC Y... 
ESC. [ee « 


Refer to documentation supplied with the specific terminal(s) in use 
for correct use of escape sequences. 


2.7 VERTICAL FORMAT CONTROL 
Table 2-11 is a summary of all characters used for vertical format 
control on the terminal. Any one of these characters can be specified 


as the value of the vfc parameter in IO.WLB, IO.WVB, IO.WBT, I0.CCO, 
or IO.RPR functions. 


1. Four control characters are allowed: CTRL/Q, CTRL/S, CTRL/X, and 

CTRL/O. These characters are handled normally by the operating system 

even when an eScape sequence is in progress. For example, entering: 
ESC CTRL/S A 


gives: 


OSB IS.ESQ 
eve cieeeen 


with the additional effect of turning off the output stream. 
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2.8 AUTOMATIC CARRIAGE RETURN 


Individual terminals can be set for wrap-around, as desired, using the 
MCR SET command 


>SET /WRAP=TTxx: 


Once wrap-around has been selected, the column at which wrap-around 
occurs can be selected using the MCR SET command 


>SET /BUF=TI:n 
> 


The SET /BUF command can also be used without an argument to display 
the current buffer width for a terminal: 


>SET /BUF=TI: 
BUF=TI:00072. 
> 


Table 2-11 
Vertical Format Control Characters 


Octal 
Value Character Meaning 


SINGLE SPACE - Output one line feed, print the 


contents of the buffer, and output a carriage 
return. Normally, printing immediately follows 
the previously printed line. 


DOUBLE SPACE - Output two line feeds, print the 
contents of the buffer, and output a carriage 
return. Normally, the buffer contents are 
printed two lines below the previously printed | 
line. 


1 PAGE EJECT - If the terminal supports FORM 
FEEDS, output a form feed, print the contents of 
the buffer, and output a carriage return. If 
the terminal does not support FORM FEEDs, the 
driver simulates the FORM FEED character by 
either outputting four line feeds to acrt 
terminal, or by outputting enough line feeds’ to 
advance the paper to the top of the next page on 
a printing terminal. 


061 


OVERPRINT - Print the contents of the buffer and | 
output a carriage return, normally overprinting | 


044 PROMPTING OUTPUT - Output one line feed and 
print the contents of the buffer. This mode of 
output is intended for use with a terminal on 
which a prompting message is output, and input 
is then read on the same line. 

000 INTERNAL VERTICAL FORMAT - Print the buffer 
contents without addition of vertical format 
control characters. In this mode, more than one 


io previous line. 
es of guaranteed contiguous output can be 


printed for each I/O request. 


f. 
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All other vertical format control characters are interpreted as blanks 
(040). 


A task can determine the buffer width by issuing a Get LUN Information 
directive and examining word 5 returned in the buffer. 


After the SET has been done, typing beyond the buffer width results in 
a carriage return and line feed being output before the next character 
is echoed. Although only one line only was input, it is displayed on 
two terminal lines. 


It is possible to lose track of where you are in the input buffer if 
wrap-around is enabled for your terminal. For example, while deleting 
text on a wrapped line, the cursor will not back up to the previous 
line. In order to resynchronize the cursor with the contents of the 
incomplete input buffer, type CTRL/R (if this SYSGEN option has’ been 
selected). 


2.9 FEATURES AVAILABLE BY RSX-11M SYSGEN OPTION 


A number of terminal-driver features are available as RSX-11M SYSGEN 
options. (See the RSX-11M System Generation and Installation Guide). 


Features previously discussed that are not repeated in this section 
include: 


e Some device-specific QIO functions (see Section 2.3.2) 


e Special keys: CTRL/R -- Write incomplete input buffer (see 
Section 2.5.1) 


CRT rubout (see Section 2.5.2) 
e Escape sequences (see Section 2.6) 


The only remaining features selected at SYSGEN time are 
terminal-independent curSor control (described in Section 2.15), 
private buffer pool size, and hard receive error detection, described 
in the following sections. 


2.9.1 Private Buffer Pool Size 


The private buffer pool is contained within the full-duplex terminal 
driver. The size of the whole driver is established during SYSGEN by 
the VMR command to load the driver as follows: 


LOA TT:/SIZE=nnn 


The private buffer pool occupies all of the space from the top of the 
actual driver code up to nnn. The argument nnn is expressed in octal 
words, and the maximum value is 20000, corresponding to 8K _ words. 
Depending on driver options selected, the code requires from 2.5 to 
4.5k words. Thus, the maximum buffer pool size is from 3.5k to 5.5k 
words. 


Alternatively, on an RSX-11M-PLUS system, it is possible to allocate 
the private pool in a separate common block called TTCOM. This block 
can range in size up to 4k words. The default size is 4k words, but 
it is modifiable, using the SIZE keyword with the VMR LOA command. In 
this case, the private pool is used almost exclusively for data 
buffers. Other driver-specifc data is allocated from secondary pool. 


FULL-DUPLEX TERMINAL DRIVER 


2.9.2 Hard Receive Error Detection 


All terminal interfaces supported by the full-duplex terminal driver 
are capable of detecting and flagging hard receive errors. Hard 
receive errors include framing errors, enable character parity error, 
and data overrun error. 


NOTE 


The driver does not enable parity 
generation and checking on DH11 and DZ11 
interfaces. 


If the hard receive error detection SYSGEN option (TSSRED) is 
selected, the driver handles hard receive errors as follows: 


1. If a read request is being processed and the character can be 
processed immediately, the read request is terminated with 
one of the following error codes returned in the status 


block: 
Error 
Code Hard Receive Error 
IE.BCC Framing error 
IE.DAO Data overrun 
IE.VER Character parity error 


2. If a command line is being input for a command line 
interpreter task and the character can be_ processed 
immediately, a CTRL/U is simulated, “U is echoed, and the 
input is terminated. No command line is sent to the task. 


3. If the character would normally cause an AST if no error was 
detected, the character is ignored and no AST occurs. 


4. If the character cannot be processed immediately, it is 
stored in the type-ahead buffer. A flag is set for the line, 
indicating that the last character in the type-ahead buffer 
has an error, disabling further storage in the type-ahead 
buffer. When the character is retrieved from the buffer, the 
appropriate action previously described is taken and the flag 
is cleared. Any characters received in the meantime are 
discarded, with a bell echoed for each character. 


If the TSSRED option is not selected, hard receive errors are ignored. 


2.10 TASK BUFFERING OF RECEIVED CHARACTERS 


When task-buffering received characters, characters read from the 
terminal are sent directly to the task's buffer. Thus, there is no 
need to allocate a terminal driver buffer. 


Task buffering of received characters does not necessarily reduce 
system overhead. For example, in a mapped system each character must 
be mapped to the task's buffer. However, if terminal driver buffering 
was used, the mapping is only done once for all characters to be 
transferred. 
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With the full duplex terminal driver, output buffering is always 
performed. 


Task buffering is overridden during checkpointing. If a task js 
checkpointable, a driver buffer is allocated and the task is made 
eligible for checkpointing by any task, regardless of priority, while 
the read operation is in progress. (Checkpointing only occurs in this 
situation when there is another task that can be made active.) Since 
checkpointability is controlled by the task, the user retains control 
over this operation. 


2.11 TYPE-AHEAD BUFFERING 


Characters received by the terminal driver are either processed 
immediately or stored in the type-ahead buffer. The type-ahead buffer 
allows characters to be temporarily stored and retrieved FIFO. The 
type-ahead buffer is used as follows: 


1. Store in buffer: 


An input character is stored in the type-ahead buffer if one 
or more of the following conditions are true: 


e The driver is not ready to accept the character (fork 
process pending or in progress). 


e There is at least one character presently in the 
type-ahead buffer. 


e The character input requires echo and the output line to 
the terminal is presently busy outputting a character. 


e No read request is in progress, no unsolicited input AST 
is specified, and the terminal is attached. 


NOTE 


Depending on the terminal mode and the presence of a 
read function, read subfunctions and an unsolicited 
input AST, the CTRL/C, CTRL/O, CTRL/Q, CTRL/S, and 
CTRL/X characters may be processed immediately and 
not stored in the type-ahead buffer. 


A character is not echoed when it is stored in the buffer. 
Echoing a character is deferred until it is retrieved from 
the buffer, since the read mode (for example, 
read-without-echo) is not known by the driver until then. 


2. Retrieve from buffer: 


When the driver becomes ready to process input, or when a task issues 
a read request, an attempt is made to retrieve a character from the 
buffer. If this attempt is successful, the character is processed and 
echoed, if required. The driver then loops, retrieving and processing 
characters until either the buffer is empty, the driver becomes unable 
to process another character, or a read request is finished with the 
terminal attached. 
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3. Flush the buffer: 

The buffer is flushed (cleared) when: 
l. CTRL/C is received. 
2. CTRL/X is received. 
3. The terminal becomes detached. 


Exceptions: CTRL/C and CTRL/X do not flush the buffer Lf 
read-pass-all or read-with-special-terminators is in effect. 


If the buffer becomes full, each character that cannot be entered 
causes a BELL character to be echoed to the terminal. 


If a character is input and echo is required, but the transmitter 
section is busy with an output request, the input character is held in 
the type-ahead buffer until output (transmitter) completion occurs. 


2.12 FULL-DUPLEX OPERATION 


When a terminal line is in the full-duplex mode, the full-duplex 
driver attempts to simultaneously service one read request and one 
write request. The Attach, Detach and Set Multiple Characteristics 
functions are only performed with the line in an idle state (not 
executing a read or a write request). 


2.13 PRIVATE BUFFER POOL 


The driver has a private buffer pool for intermediate input and output 
buffers on both RSX-11M and RSX-11M-PLUS systems, and type-ahead 
buffers and UCB extensions on RSX-11M systems only. Whenever the 
driver needs dynamic memory, it first attempts to allocate a buffer in 
the private pool. If this fails, a second attempt is made in the 
system pool. If the allocation in the system pool fails during 
command line input, a CTRL/U is simulated and echoed. 


Command line interpreter task buffers are handled in a special way. 
When unsolicited input begins, a buffer is allocated, as previously 
described, for the command line (a string of characters, followed by 
an appropriate terminator character). When the input is completed, 
the contents of the buffer is sent directly to the command line 
interpreter task if the buffer was allocated in the system pool. 
However, if the buffer was allocated in the driver's private pool, it 
Must first be moved into a buffer in the system pool to provide access 
for the task. 


2.14 INTERMEDIATE INPUT AND OUTPUT BUFFERING 


Input buffering for checkpointable tasks with checkpointing enabled is 
provided in the private pool. As each buffer becomes full, a new 
buffer is automatically allocated and linked to the previous buffer. 
The Executive then transfers characters from these buffers to the task 
buffer and the terminal driver deallocates the buffers once the 
transfer has been completed. 
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If the driver fails to allocate the first input buffer, the characters 
are transferred directly into the task buffer. If the first buffer is 
successfully allocated, but a subsequent buffer allocation fails, the 
input reguest terminates with the error code IE.NOD. In this case, 
the I/O status block contains the number of characters actually 
transferred to the task buffer. The task may then update the buffer 
pointer and byte count and reissue a read request to receive the rest 
of the data. The type-ahead buffer ensures that no input data is 
lost. 


All terminal output is buffered. As many buffers as required are 
allocated by the terminal driver and linked to a list. If not enough 
buffers can be obtained for all output data, the transfer is done as a 
number of partial transfers, using available buffers for each partial 
transfer. This is transparent to the requesting task. If no buffers 
can be allocated, the request terminates with the error code IE.NOD. 


The unconditional output buffering serves three purposes: 
1. It reduces time spent at system state. 
2. It enables long DMA transfers for DH1l controllers. 


3. It enables task checkpointing during the transfer to the 
terminal (if all output fits in one buffer list). 


2.15 TERMINAL-INDEPENDENT CURSOR CONTROL 


Terminal-independent cursor control capability is provided at SYSGEN 
time. The terminal driver responds to task I/O requests for cursor 
positioning without the task requiring information about the type of 
terminal in use. I/O functions associated with cursor positioning are 
described as follows. 


Cursor position is specified in the vfc parameter of the I0O.WLB or 
IO.RPR function. The parameter is interpreted simply as a vfc 
parameter if the high byte of the parameter is 0. However, if the 
parameter is used to define cursor position, the high byte must be 
nonzero, the low byte is interpreted as column number (x-coordinate), 
and the high byte is interpreted as line number (y-coordinate). Home 
position, the upper left corner of the display, is defined as 1,1. 
Depending upon terminal type, the driver outputs appropriate 
cursor-positioning commands appropriate for the terminal in use that 
will move the cursor to the specified position. If the most 
Significant bit of the line number is set, the driver clears’ the 
display before positioning the cursor. 


When defining cursor position in an I0.WLB function, the TF.RCU 
subfunction can be used to save the current cursor position. When 
included in this manner, TF.RCU causes the driver to first save the 
current cursor position, then position the cursor and output the 
specified buffer, and, finally, restore the cursor to the original 
(saved) position once the output transfer has been completed. 


2.16 TERMINAL INTERFACES 
This section summarizes’ the characteristics of the standard 


communication-line interfaces supported by RSX-11M. Refer to the 
Terminals and Communications Handbook for additional details. 
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2.16.1 DH11 Asynchronous Serial Line Multiplexer 


The DH11 multiplexer interfaces up to 16 asynchronous serial 
communications lines for terminal use. The DH1l supports programmable 
baud rates. Input and output baud rates may differ; the input rate 
may be set to 0 baud, thus effectively turning off the terminal. The 
DM11-BB option may be included to provide modem control for dial-in 
lines. These lines must be interfaced by means of a full duplex modem 
(for example, in the United States, a Bell 103A or equivalent modem). 


2.16.2 DHV11 Asynchronous Serial Line Multiplexer 


The DHV11 multiplexer interfaces up to eight asynchronous’ serial 
communications lines for terminal use. This multiplexer is the Q BUS 
version of the DH1l UNIBUS multiplexer. The DHV11 supports 
programmable baud rates with the option of selecting split speed 
operation. (Split speed operation allows different transmit and 
receive speeds.) Also provided is modem control for full-duplex 
point-to-point operation. 


2.16.3 DJ11 Asynchronous Serial Line Multiplexer 


The DJ11 multiplexer interfaces as many as 16 asynchronous’ serial 
lines to the PDP-11 for local terminal communications. The DJ1l does 
not provide a dial-in capability. Baud rates are jumper selectable. 


2.16.4 DL11 Asynchronous Serial Line Interface 


The DL11 supports a single asynchronous serial line and handles 
communication between the PDP-11l and a terminal. A number of standard 
baud rates are available to DL11 users. However, since the DL11 does 
not have an input silo, baud rates greater than 1200 baud are not 
recommended. Higher baud rates may cause input characters to be lost. 


For hardware reasons, a DL1l is susceptible to losing receiver 
interrupt enable in its Receiver Status Register. The disabling of 
the receiver interrupt bit causes the terminal to print output 
requests but not to respond to input (for example, the terminal does 
not echo input characters). The terminal driver has no mechanism for 
recognizing the disabling. Therefore, it cannot recover. The bit 
must be reset with an MCR OPEN command, the console switch register, 
or a periodically rescheduled task. 


2.16.5 DZ11 Asynchronous Serial Line Multiplexer 


The DZ11 multiplexer interfaces up to eight asynchronous” serial 
communication lines for use with terminals. It supports programmable 
baud rates; however, transmit and receive baud rates must be the 
same. The DZ1l1 can control a full duplex modem in auto-answer mode. 
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2.17 PROGRAMMING HINTS 
2.17.1 ESCape Code Conversion 


If escape sequences are recognized, the character code 037 will 
terminate input and a status code IS.ESC is returned. In addition, 
character codes will terminate input and return the IS.ESC status if 
upper- to lowercase conversion is not enabled. 


2.17.2 RTO02-C Control Function 


Because the screen of an RTO02C Badge Reader and Data Entry Terminal 
holds only one line of information, special care must be taken when 
sending a control character (for example, vertical tab) to the RT02-C. 
Use the IO.WAL (Write All) function for this purpose. 


It is recommended that read without echoing be used when reading a 


badge with the RTO2-C. Use IO.RAL or I0.RNE functions, followed by 
the IO.WAL function, to echo the information for display. 
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2.17.3 Using IO.WVB Instead of IO.WLB 


Using IO.WVB instead of IO.WLB is recommended when writing to a 
terminal. If the write actually goes to a terminal, the Executive 
converts the IO.WVB to an IO.WLB request. However, if the LUN has 
been redirected to an inappropriate device (for example, a disk), the 
use of an IO.WVB function will be rejected because a file is not open 
on the _ LUN. This prevents privileged tasks from overwriting block 
zero of the disk. 


Note that any subfunction bits specified in the I0.WVB request (for 


example, TF.CCO, TF.WAL, or TF.WBT) are stripped when the IO.WVB is 
converted to an IO.WLB. 


2.17.4 Remote DL11-E, DH11, and DZ11 Lines 


e 


Before a remote line is answered, the driver clears certain terminal 
characteristics (see Table 2-5) that may have been set by an MCR SET 
command, or by an SF.SMC function. The characteristics cleared are: 
TC.SCP, TC.ESQ, TC.HED, TC.SMR, TC.MEC, TC.FDX, TC.HFF, TC.HHT, 
TC.YPL, TC.HFL, TC,?PTP, TCeB8BC, and TC-BEN. (Clearing TC.TTP means 
that a terminal type of "unknown" will be returned in an SF.GMC 
request.) The TC.ACR characteristic (automatic wrap around) iS set. 
Buffer size is set to 72. 


ane! 


A DZ11 remote line must be declared to be remote before the terminal 
driver will handle the modem. 


2.17.5 Side Effects of Setting Characteristics 


Certain terminal characteristics that a task may set or that an 
operator may set using MCR commands may have undesirable side effects. 
In particular, these characteristics include the hold-screen mode and 
the lower- to uppercase converSion disable mode. Their effects are 
described as follows. 


TC.HLD -- Unexpected behavior can result from a terminal in the 
hold-screen mode if its reception rate is much greater than its 
transmission rate. (The DH11 supports split baud rates.) When in the 
hold-screen mode, the terminal automatically sends a CTRL/S during 
reception of an output stream when the screen is nearly full. Output 
is resumed -- another screen-full -- when you type SHIFT/SCROLL (the 
terminal generates CTRL/Q). Thus, no output is lost as a result of 
scrolling off the screen before you can read it. However, if the 
terminal's transmission rate is far below its reception rate, some 
unread output may scroll out of sight before the CTRL/S can be 
transmitted. 


Note that some terminals and interfaces are hardware buffered. This 
can cause obScure timing problems for tasks that attempt to invoke the 
hold-screen mode. 


TC.SMR -- If this characteristic is asserted (lower- to uppercase 
conversion is disabled), octal characters 175 and 176 are interpreted 
as “right brace ( ay and "tilde (~)," respectively. If TC.SMR is 
not asserted, these characters are interpreted as an Altmode (that is, 
they function as line terminators that do not advance the cursor to a 
new line). 
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2.17.6 Modem Support 

The terminal driver supports the following modem control operations: 
e Local or remote operation 
e@e Answer speed 
e Auto-baud speed detection 


The characteristics bit that controls local or remote operation is 
TC.DLU. This bit can be set with the MCR command SET /REMOTE (or SET 
/NOREMOTE for local operation). The DCL command SET TERMINAL REMOTE 
(or SET TERMINAL LOCAL) can also be used. 


When there is an incoming call on a remote line, the TC.ASP . 
characteristic determines the baud rate for the answering modem. 


Split baud rates (different transmit and receive speeds) are not 
supported for answer speed. 


The default answer speed is set at SYSGEN time. However, the answer 
speed can be set on line using the MCR command SET /REMOTE=TTnn:speed. 
VMR can also be used to set the answer speed. 


The terminal driver can determine the speed of the incoming call by 
sampling the first input character after dial-up for the following 
speeds: 


110 
150 
300 
1200 


This is called auto-baud speed detection. This option can be selected 
for each line using the SET /ABAUD command. This command sets the 
TC.ABD terminal characteristic. When TC.ABD is set for a given line, 
the terminal driver makes three attempts to determine the incoming 
speed. If the auto-baud speed detection fails, the terminal driver 
will use the default answer speed discussed above. 


For auto-baud speed detection to work correctly, the first input 
character after dial-up must be either carriage return or CTRL/C. 
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3.1 INTRODUCTION 


The half-duplex terminal driver provides support for a variety of 
terminal devices under RSX-11M. (This terminal driver is not 
supported on RSX-11M-PLUS systems.) The half-duplex terminal driver is 
generally used in RSX-11M systems where small driver size is 
essential, and the additional functional capability provided by the 
larger full-duplex terminal driver (described in Chapter 2) is not 
required. Table 3-1 summarizes’ the terminals supported, and 
subsequent sections describe these devices in greater detail. 


Table 3-1 
Supported Terminal Devices 


Model Columns | Lines/ Characte Baud Upper- & Lowercase? 
Screen! | __set__| Range 
72 64 


ASR-33/35 110 
KSR=-33/35 a2 64 110 
LA12 132 96 50-9600! yes | yes 


LA100 | 96 110-9600 yes yes 
LA30-P 64 300 

LA30-S 64 110=3:00 

LA34 96 110-300 yes yes 
LA36 64-96 {110-300 yes yes2 
LA38 96 110-300 yes yes 
LA120 96 50-9600 yes yes 
LA180S 96 300-9600 yes 
RTO02 1 64 110-1200 

RTO2-C 1 64 110-1200 

VTO5B 20 64 110-2400 yes 

VT50 12 64 110-9600 

VT50H 12 64 110-9600 

VT52 24 96 110-9600 yes yes 
VT55 24 96 110-9600 yes yes 
VT6l1 24 96 110-9600 yes yes 
VT100 24 96 50-9600 yes yes 
VT101 24 96 50-19200 yes yes 
VT102 24 96 50-9600 yes yes 
VT105 24 96 50-9200 yes yes 
VILZS 24 96 50-9600 yes yes 
VT131 80-132 24 96 50-19200 yes yes 
VT132 80-132 24 96 50-19200 yes yes 


1. Applies only to video terminals. 


2. Only for 96-character terminal. The terminal driver supports 
the terminal interfaces summarized in Table 3-2. These interfaces 
are described in greater detail in Section 3.9. Programming is 
identical for all. 
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Table 3-2 
Standard Terminal Interfaces 


pment 


DH11 16-line multiplexer+ 

DH11-DM11-BB 16-line multiplexer with modem control2 
DJ11 16-line multiplexer 

DL11-A/B/C/D/W Single-line interfaces 

DLV11-F Single-line interface 

DZ11 8-line multiplexer with modem controi2 


1. Direct memory access (DMA) not supported. 


2. Full-duplex control only. For example, in the USA, a 
Bell 103A-type modem. 


Terminal input lines can have a maximum length of 255 bytes (the 
maximum is set in the system generation, or SYSGEN, dialog). The 
extra characters of an input line that exceeds the maximum length 
generally become an unsolicited input line. 


3.1.1 ASR-33/35 Teletypest 


The ASR-33 and ASR-35 Teletypes are asynchronous, hard-copy terminals. 
No paper tape reader or punch capability is supported. 


3.1.2 KSR-33/35 Teletypesl 


The KSR-33 and KSR-35 Teletypes are asynchronous, hard-copy terminals. 


3.1.3 LA30 DECwriters 
The LA30 DECwriter is an asynchronous, hard-copy terminal that is 


capable of producing an original and one copy. The LA30-P is a 
parallel model and the LA30-S is a serial model. 


3.1.4 LA36 DECwriter 
The LA36 DECwriter is an asynchronous terminal that produces hard copy 
and operates in serial mode. It has an impact printer capable of 


generating multipart and special preprinted forms. The LA36 can 
receive and transmit both uppercase and lowercase characters. 


1. Teletype is a registered trademark of the Teletype Corporation. 
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3.1.5 LA120 DECwriter 


The LA120 DECwriter is a hard-copy, upper- and lowercase terminal 
capable of printing multipart forms at speeds up to 180 
characters-per-sSsecond. Serial communications speed is selected from 
14 baud rates ranging from 50 to 9600 bps. Hardware features allow 
bidirectional printing for maximum printing speed, and also allow 
user-selected features, including font size, line spacing, tabs, 
margins, and forms control. These functions can also be set up by 
user tasks that issue appropriate ANSI-standard escape sequences. 


3.1.6 LA180S DECprinter 


The LA180S DECprinter is a serial version of the LA180. It is a 
print-only device (it has no keyboard) that can generate multipart 
forms. The LA180S can print uppercase and lowercase letters. 


Sele t RTO2 Alphanumeric Display Terminal and RT02-C Badge Reader/ 
Alphanumeric Display Terminal 


The RTO2 is a compact, alphanumeric display terminal designed for 
applications in which source data is primarily numeric. A shift key 
permits the entry of 30 discrete characters, including uppercase 
alphabetic characters. The RTO2 can, however, receive and display 64 
characters. 


The RTO2-C model also contains a badge reader. This option provides a 
reliable method of identifying and controlling access to the PDP-11 or 
to a secure facility. Furthermore, data in a format corresponding to 
that of a badge (22-column fixed data) can be entered quickly. 


3.1.8 VTO5B Alphanumeric Display Terminal 


The VTO5B is an alphanumeric display terminal that consists of a CRT 
display and a_ self-contained keyboard. From a programming point of 
view, it is equivalent to other terminals, except that the VTO5B 
offers direct cursor addressing. 


3.1.9 VTSO Alphanumeric Display Terminal 


The VT50 is an alphanumeric display terminal that consists of a CRT 
display anda keyboard. It is similar to the VTO5B in operation, but 
does not offer direct cursor addressing. 


3.1.10 VTSOH Alphanumeric Display Terminal 


The VT50H is an alphanumeric display terminal with CRT display, 
keyboard, and numeric pad. It offers direct cursor addressing. (The 
VT50H's direct cursor addressing is not compatible with that of the 
VTO5B.) 
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3.1.11 VT52 Alphanumeric Display Terminal 


The VT52 is an upper- and lowercase alphanumeric terminal with numeric 
pad and direct cursor addressing. (The VT52's direct cursor 
addressing is compatible with that of the VT50H, but not with that of 
the VTO5B.) The VT52 can be configured with a built-in thermal 
printer. 


3.1.12 VT55 Graphics Display Terminal 


The VT55 is similar to the VT52 in its operation as an alphanumeric 
terminal. The VT55 offers graphics display features that are not 
supported by RSX-11M, although the system allows a knowledgeable task 
to access the explicitly special features of the VT55. 


3.1.13 VT61 Alphanumeric Display Terminal 


The VT61 is an "intelligent" upper- and lowercase alphanumeric 
terminal with an integral microprocessor. It offers two 128-member 
character sets and numerous built-in functions for editing and 
preparing forms, as well as a block-transfer mode. (None of these 
special features is supported by RSX-11M.) 


3.1.14 VT100 DECscope 


The VT100 DECscope is an upper- and lowercase alphanumeric 
keyboard/video display terminal. It is capable of displaying 24 lines 
of 80 characters (each line). Serial communications speed is selected 
from baud rates ranging from 50 to 9600 bps. Hardware features allow 
user Selection of display characteristics and functions’ including 
smooth scroll, reverse video, and so forth. These functions can also 
be set up by user tasks that issue appropriate ANSI-standard escape 
sequences. 


3.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the Get LUN [Information system 
directive (the first characteristics word) contains the following 
information for terminals. A setting of 1 indicates that the 
described characteristic is true for terminals. 


Bit Setting Meaning 
0 A Record-oriented device 
1 1 Carriage-control device 
2 1 Terminal device 
3 0 File structured device 
4 0 Single-directory device 
5 0 Sequential device 
6 0 Mass storage device 
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Bit Setting Meaning 
7 0 User-mode diagnostics supported 
8 0 Device supports 22-bit direct addressing 
9 0 Unit software write-locked 
10 0 Input spooled device 
ALE 0 Output spooled device 
12 0 Pseudo device 
13 0 Device mountable as a communications 
channel 
14 0 Device mountable as a FILES-11 volume 
LS 0 Device mountable 


Words 3 and 4 are undefined. Word 5 indicates the default buffer 
size for the device: for terminals the width of the terminal carriage 
or display screen. 


3.3 QI0 MACRO 


Table 3-3 lists the standard and device-specific functions of the QIO 
macro that are valid for terminals. All device-specific functions are 
options that may be selected at system generation. 


Two device-specific functions, SF.SMC and SF.GMC, have nonstandard 


function names. These names are designed for compatibility with IAS. 


Table 3-3 
Standard and Device-Specific QIO Functions for Terminals 


STANDARD FUNCTIONS: 


OLOSC TOV ATT: is << Attach device 
OLOSC> 10. DET... Detach device 
OL0SC 10.KIL. Cancel I/O requests 


QIOSC IO.RLB,...,<stadd,size> READ logical block 
(read typed input into buffer) 


OLOSC. 1O.,RVB Ys ,<stadd,size> READ virtual block 
(read typed input into buffer) 


° 
mes ~ se a 


f Kee LL 
{print putter cont 


QIOSC IO.WLB,...,<stadd,size,vfc> | WRITE logical k 
e 


QIOSC IO.WVB,...,<stadd,size,vfc> | WRITE virtual block 
(print buffer contents). 


(continued on next page) 
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Table 3-3 (Cont.) 
Standard and Device-Specific QIO Functions for Terminals 


DEVICE-SPECIFIC FUNCTIONS 
| (ALL SYSGEN OPTIONS) : 


QIOSC IO.ATA,...,<ast> ATTACH device, specify 
unsolicited- input-character 
AST 


QIOSC I0.CCO,...,<stadd,size,vfc> | CANCEL CTRL/O (if in effect), 
then write logical block 


QIOSC SF.GMC,...,<stadd,size> GET multiple characteristics 

QIOSC IO0.GTS,...,<stadd,size> GET terminal support 

QIOSC IO.RAL,...,<stadd,size> READ logical block, pass all 
bits 

QIOSC IO.RNE,...,<stadd,size> READ logical block, do not echo 

QIOSC IO.RPR,...,<stadd,size, READ logical block after prompt 

{tmo] ,pradd,prsize,vfc> 

QIOSC IO.RST,...,<stadd,size> READ logical block ended by 
special terminators 

QIOSC SF.SMC,...,<stadd,size> SET multiple characteristics 

QIOSC IO.WAL,...,<stadd,size> WRITE logical block, pass all 
bits 


QIOSC IO.WBT,...,<stadd,size,vfc> | WRITE logical block, break 
through most I/O conditions at 
terminal 


ast 


The entry point for an unsolicited-input-character AST. 


pradd 


The starting address of the byte buffer where the prompt is 
stored. The buffer must be within the task's address space. 


prsize 


The size of the pradd prompt buffer in bytes. If the system 
Supports variable length reads, the buffer size must be greater 
than 0 and less than or equal to 255. If the system does not 
support variable length reads, the specified size must be greater 
than 0 and less than or equal to 80. 
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size 


The size of the stadd data buffer in bytes (must be greater than 
Ox If the function is a read and the system supports 
variable-length reads, the size must be less than or equal to 
2508 Otherwise, the size must be less than or equal to 80. The 
buffer must be within the task's address_ space. For SF.GMC, 
IO.GTS, and SF.SMC, the size must be an even number less than 
4065 (decimal). If the function is a write, size can be up _ to 
32K bytes. 


stadd 
The starting address of the data buffer. The address must be 
word aligned for SF.GMC, I0O.GTS, and SF.SMC; otherwise, stadd 
may be on a byte boundary. 

tmo 
An optional time-out count, included for IAS compatibility. Le 
supplied, it is ignored. 

vfc 


A character for vertical format control from Table 3-11 (see 
Section 3.7). 


3.3.1 Subfunction Bits 


Most of the device-specific functions supported by the terminal driver 
are implemented by way of "subfunction bits." That is, these functions 
can be invoked by ORing a named bit with some other function. Table 
3-4 shows the relationship of the 10 subfunction bits to the standard 
and device-specific functions. 


The 10 subfunction bits, and their octal values, are: 


TF.AST Unsolicited-input~character AST 10 
TF.BIN Binary prompt 2 
TF.CCO Cancel CTRL/O 40 
TF.ESQ Recognize escape sequences 20 
TF.RAL Read all bits 10 
TF.RNE Read with no echo 20 
TF.RST Read with special terminators 1 
TF .WAL Write all bits 10 
TF.WBT Break-through write 100 
TF.XOF Send XOFF 100 


The subfunction bits are defined in the system module TTSYM (discussed 
further in Section 3.3.2.5). The octal values of these entities are 
subject to change; therefore, it is recommended that you always use 
the symbolic names. As Table 3-4 shows, 7 of the 10 subfunction bits 
can be ORed with standard QIO functions to invoke device-specific 
functions. The remaining three subfunction bits (TF.BIN, TF.ESOQ, and 
TF.XOF) can be ORed with Attach and Read After Prompt QIOs to. provide 
added features, aS described in Section 3.3.2. 
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Of the 10 subfunction bits, 3 can be used with Read QIO functions, 3 
with Write functions, 2 with Attach functions, and 5 with Read After 
Prompt. The breakdown is: 


Read TF.RAL, TF.RNE, TF.RST 

Write TF.CCO, TF.WAL, TF.WBT 

Attach TF.AST, TF.ESO 

Read After Prompt TF.BIN, TF.XOF, TF.RAL, TF.RNE, TF.RST 


If a task invokes a subfunction bit that is not supported on the 
system, the subfunction bit is ignored, not rejected. For example, if 
Read with Special Terminators is not selected, either I0.RST or 
IO.RLB!ITF.RST is interpreted as IO.RLB. 


The following example shows a QIO request using more than one 
subfunction bit: a nonechoed read, which may be concluded by a 
Special terminator, after a prompt. 


QIOSC IO.RPR!ITF.RNE! TF.RST,...,<Stadd,size,,pradd,prsize,vfc> 


3.3.2 Details on Device-Specific QIO Functions 


All the device-specific functions described in this section are SYSGEN 
options. All except SF.GMC, IO.RPR, SF.SMC, and I0.GTS can be issued 
by ORing a particular subfunction bit with another QIO function. 
These subfunction bits are specified in the text; subfunction bits 
are described in general in Section 3.3.1. 


In addition to the 11 device-specific QIO functions, this section also 
gives details on the features provided by the 3 subfunction bits 
TF.ESQ, TF.BIN, and TF.XOF. 


3.3.2.1 I0O.ATA - IO.ATA is a variation of the Attach directive. It 
specifies an asynchronous system trap (AST) to process an unsolicited 
input character. When called as follows: 


QIOsc IO.ATA,...,<ast> 


this function attaches the terminal and identifies "ast" as the entry 
point for an unsolicited-input-character AST. Control passes to this 
address whenever any unsolicited character (other than CTRL/Q, CTRL/S, 
or CTRL/O) is input. Note that little checking is done on the 
specific AST address. A bad address is frequently detected only when 
the Executive tries to transfer control to it and the task crashes. 


In particular, CTRL/C is trapped by the task and does not reach MCR. 
Thus, any task that uses IO.ATA should recognize some-input sequence 
aS a request to terminate, because MCR can not be invoked to abort the 
task in case of difficulty. 


Note that this mechanism is intended to get a single character into 
the system -- not a series of characters. Since the driver must 
become a fork process in order to declare an AST, a second character 
can.arrive before the driver can queue an AST for the first character. 
The buffer for unsolicited input characters, however, is one byte 
long. Therefore, the terminal driver ignores the second character. 
This circumstance can occur because of fast input on a busy system or 
because output is in progress when the characters are received. The 
implications of this are that neither type-ahead nor full-duplex 
operations can be simulated perfectly using unsolicited character 
ASTs. 
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Table 3-4 
Subfunction Bits 


Allowed Subfunction Bits 


Function | Equivalent with Te tyeret 
subfunction bits | TF.AST | TF.BIN| TF.CCO | TF.ESQ | TF.RAL TF.RST | TF.WAL | TF.WBT | TF. XOF 


TF.RNE 


IO.ATT X xX 

I0O.DET 

IO.KIL 

IO.RLB 

I0.RVB 

IO.WLB Xx xX 
IO.WVB 2 2 
IO.ATA IO.ATT!TF.AST x 

I0.Ccco IO.WLB! TF.CCO Xx Xx 
SF.GMC 

I0.GTS 

I0.RAL IO.RLB! TF.RAL 

IO. RNE IO.RLB! TF.RNE 

IO.RPR X x 
IO.RST IO.RLB!TF.RST 

SF.SMC 

IO.WAL IO.WLB! TF.WAL xX 
TIO.WBT IO.WLB!TF.WBT xX 


1. Exercise great care when uSing Read All and Read with Special Terminators together. Obscure problems can 
result. 


2. These subfunction bits are allowed but are not effective. They are stripped off when the read or write 
virtual is converted to a read or write logical. 


UAAIYC IWNIWYAL Xa IdNd-dATVH 
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At entry, the unsolicited character is the low-order byte of the top 
word on the stack. Before exiting the AST, be sure to pop that word 
off the stack; otherwise, the task will crash. In all other respects 
the AST environment is standard: 


SP+10 Event flag mask word 

SP+06 PS of task prior to AST 

SP+04 PC of task prior to AST 

SP+02 Task's directive status word 
SP+00 Unsolicited character in low byte 


See the RSX-11M/M-PLUS Executive Reference Manual for further details 
on ASTs. See Section 3.10.10 for hints on ASTs in a multiterminal 
environment. 


IO.ATA is equivalent to IO.ATT ORed with the subfunction bit TF.AST. 


3.3.2.2 IO.ATTITF.ESQ - The task issuing this directive attaches a 
terminal and notifies the driver that it recognizes escape Sequences 
input from that terminal. Escape sequences are recognized only for 
solicited input. See Section 3.6 for a discussion of escape 
sequences. 


If the terminal has not been declared capable of generating escape 
sequences, IO.ATT!ITF.ESQ has no effect beyond attaching the terminal. 
No eScape sequences are returned to the task, because any ESC sent by 
the terminal acts aS a line terminator. The SF.SMC QIO or the MCR SET 
/ESCSEQO command is used to declare the terminal capable of generating 
escape sequences (see Table 3-5 and Section 3.3.2.12). 


3.3.2.3 I10.CCO - This write function directs the driver to write to 
the terminal regardless of a CTRL/O condition that may be in effect. 
If CTRL/O is in effect, it is canceled before the write is done. 


I0.CCO is equivalent to IO.WLB!ITF.CCO. 


3.3.2.4 SF.GMC - The Get Multiple Characteristics function returns 
information on terminal characteristics. Get Multiple Characteristics 
is used in the following way: 


QIOSC SF.GMC,...;<stadd,size> 


stadd 


The starting address of a data buffer of length "size" bytes. 
Each word in the buffer has the form 


-BYTE characteristic-—name 
-BYTE 0 
characteristic-name 


One of the eight bit names given in Table 3-5. 
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The QIO function returns a value in the high-order byte of each 
byte-pair: 1 if the characteristic is true for the terminal, 0 if not 
true. 


For the TC.TTP characteristic (terminal type), one of three values is 
returned in the high-order byte, as shown in Table 3-6. 


NOTE 


The half-duplex terminal driver treats 
the terminal type as a required 
characteristic for the type of terminal 
specified. The terminal type (TC.TTP) 
does not set any implicit terminal 
characteristics other than those noted 
in Table 3-6. 


Table 3-5 
Terminal Characteristics for SF.GMC and SF.SMC Requests 
Bit Octal | Meaning Corresponding 
Name Value | (If Asserted): Terminal ... MCR Command 
TC.ASP3 76 Remote line answer speed SET /REMOTE=TI:speed 
TC. ESQ 35 «..can generate escape sequences | SET /ESCSEQ=TI: 
TC.HLD1L 44 ---is in hold-screen mode SET /HOLD=TI: 
TC .NEC 47 »ee-iS in no-echo mode SET /NOECHO=TI: 
TC.PRI2} 51 ...is privileged SET /PRIV=TTnn: 
TC.SCP 12 2..iS a scope (CRT) SET /CRI-=TL: 
TC.SLV 50 ---i1S Slaved SET /SLAVE=TTnn: 
TC.SMR 25 Uppercase conversion disabled SET /LOWER=TI: 
on input 
TG. TTP 10 Terminal type SET /LA30S=TI: 
SET /VTOSB=TI: 
TC.HFF 17 --ehandle hardware form feeds SET /FORMFEED=TI: 
TC.RSP3 3 Receiver speed SET /SPEED=TI:rcv:xmit 
TC.XSP? 4 Transmitter speed (As above) 


1. Effective for VT5x and VT61 only. 
2. Cannot be changed by a task; must use MCR command. 


3. Recognized only by the SF.SMC function. 


Table 3-6 
Bit TC.TTP (Terminal Type): Values Set by SF.SMC 
and Returned by SF.GMC 


T.UNKO Terminal type is unknown 
(resets all other types) 
Terminal is an ASR 

(sets uppercase conversion on 
output) 

4 T.L30S Terminal is an LA30 

(sets horizontal fill after 


carriage return) 
7 T.VTO05 Terminal is a VTO5B 
(sets a vertical fill count of 4) 


a-11 


T.AS33 
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3.3.2.5 I0.GTS - The Get Terminal Support QIO returns a 4-word buffer 
of information specifying which SYSGEN-option features are part of the 
terminal driver. Of these four words, two are currently defined. 
Table 3-7 gives details on these two words. The I0.GTS QIO is itself 
a SYSGEN option. If I0.GTS is issued on a minimum system (one with no 
terminal-driver SYSGEN options), IE.IFC is returned in the I/O status 
block. 


Table 3-7 
Information Returned by Get Terminal Support (I0.GTS) QIO 


Word 0 of Buffer: 


F1.ACR Automatic CR/LF on long lines 
F1.BTW Break-through write 
4 F1.BUF Checkpointing during terminal input 
10 F1.UIA Unsolicited-input-character AST 
20 F1.CCO Cancel CTRL/O before writing 
40 F1.ESO Recognize escape sequences in solicited input 
100 F1.HLD Hold-screen mode 
200 F1.LWC Lower- to uppercase conversion 
400 F1.RNE Read with no echo 
1000 F1.RPR Read after prompting 
2000 F1.RST Read with special terminators 
4000 F1.RUB CRT rubout 
10000 F1.SYN CTRL/R terminal synchronization 
20000 F1.TRW Read all and write all 
40000 F1.UTB Input characters buffered in task's address 
space 
100000 F1.VBF Variable-length terminal buffers 


WOOAHNOPBWNOF © 


Set characteristics QIO (SF.SMC) 
Get characteristics QIO (SF.GMC) 


The various symbols used by the I0.GTS, SF.GMC, and SF.SMC QIOs are 
defined in a system module, TTSYM. These symbols include: 1.xxx and 
F2.xxx (Table 3-7); T.xxxx (Table 3-6); TC.xxx (Table 3-5); and the 
SE.xxx error returns described in Table 3-8, Section 3.4. These 
symbols may be defined locally within a code module by using: 


.»MCALL TTSYMS 


TTSYMS 


If the symbols are not defined locally, they are automatically defined 
by the Task Builder. 


The octal values of these symbols are subject to change. Therefore, 
it is recommended that you always use the symbolic names. 
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3.3.2.6 I0O.RAL - The Read All function causes the driver to pass all 
bits to the requesting task. The driver does not intercept control 
characters or mask out the "parity" (high-order) bit. This means, for 
example, that CTRL/C, CTRL/Q, CTRL/S, CTRL/O, and CTRL/Z are passed to 
the program and are not interpreted by the driver. 


NOTE 


IO.RAL echoes the characters that are 
read. To read all bits without echoing, 
use IO.RAL!ITF.RNE. 


IO.RAL is equivalent to IO.RLB ORed with the subfunction bit MTF.RAL. 
The only way to terminate an IO.RAL function is by a character count 
(that is, filling the input buffer). 


3.3.2.7 I0O.RNE - IO.RNE causes the driver to read a line from _ the 
terminal without echoing the characters that are input. This feature 
is useful when typing sensitive information: for example, a password 
or combination. IO.RNE is also used to read a badge with the RT02-C. 


(Another way to suppress echoing of input is to set the terminal to 
no-echo mode with the SF.SMC QIO or the MCR SET /NOECHO command. See 


Note that the TC.NEC subfunction only suppresses echoing of solicited 
input. Unsolicited input is still echoed. 


CTRL/R, if selected as a SYSGEN option, is ignored while an IO.RNE is 
in progress. 


IO.RNE is equivalent to IO.RLB ORed with the subfunction bit TF.RNE. 


3.3.2.8 IO.RPR - The QIO function IO.RPR (Read After Prompt) has’ the 
same effect as IO.WLB (to write a prompt to the terminal) followed by 
IO.RLB. However, IO.RPR differs in four ways from this combination of 
QIOs. With IO.RPR: 


e System overhead is lower because only one QIO is processed. 


e There is no "window" during which a response to the prompt may 
be ignored. Such a window occurs if IO.WAL/IO.RLB is used, 
because no read may be posted at the time the response is 
received. 


e If the issuing task is checkpointable, it is checkpointed 
during both the prompt and the read. 


e A CTRL/O that may be in effect is canceled before the prompt 
is written. 


The third user-specified argument to I0.RPR, tmo, is required for 
compatibility with IAS. If supplied, it is ignored. 


Subfunction bits may be ORed with IO.RPR to write the prompt as a 
Write All (TF.BIN) and to send XOFF after the read (TF.XOF). See the 
next two sections. In addition, the three Read subfunction bits 
(TF.RAL, TF.RNE, TF.RST) can be used with IO.RPR. 
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3.3.2.9 IO.RPRITF.BIN - This QIO function results in a read after a 
"binary" prompt, that is, a prompt that is written by the driver with 
no character interpretation (as if it were issued as an IO.WAL). 


3.3.2.10 IO.RPRITF.XOF = This QIO function causes the driver to send 
an XOFF to the terminal after its prompt-and-read. The XOFF, or 
CTRL/S, may have the effect of inhibiting input from the terminal, if 
the terminal recognizes XOFF for this purpose. 


3.3.2.11 I0.RST - This QIO function acts like IO.RLB, except that 
certain special characters terminate the read. These characters are 
in the ranges 0-37(8) and 175-177(8). The driver does not interpret 
the terminating character, with certain exceptions.! For example, a 
horizontal TAB (11 octal) is not expanded, a RUBOUT (or DEL, 177 
octal) does not erase, and a CTRL/C does not get MCR's attention. 


Upon successful completion of ‘an I0.RST request that was not 
terminated by filling the input buffer, the I/O status block looks 
like the following: 


Terminating 
character 


# of bytes in buffer 


IOSB 


The terminating character is not in the buffer. 


IO.RST is equivalent to IO.RLB!ITF.RST. 


3.3.2.12 SF.SMC - This QIO function allows a task to set and reset 
the characteristics of a terminal. Set Multiple Characteristics is 
the inverse of SF.GMC. Like SF.GMC, it is called in the following 
way: 


QIOSC SF.SMC,...,<stadd,size> 


stadd 
The starting address of a buffer of length "size" bytes. 
Each word in the buffer has the form 


~-BYTE characteristic-—name 
~BYTE value 


1. If upper- and lowercase conversion is disabled (see remarks in 
Section 3.10.9), the character 175(8) echoes as right-brace and 176(8) 
as tilde, and these characters do not act as terminators. The three 
characters CTRL/O, CTRL/Q,; and CTRL/S (17, 21, and 23(8), 
respectively) are not special terminators. The driver interprets them 
as output effectors. 


HALF-DUPLEX TERMINAL DRIVER 


characteristic-—name 


One of the symbolic bit names given in Table 3-5. 


value 


Either 0 (to clear a given characteristic) or 1 (to set a 
characteristic). Table 3-5 notes the restrictions that apply to 
these characteristics. 


If characteristic-name is TC.TTP (terminal type), then value can have 
any of the values listed in Table 3-6. 


A nonprivileged task can only issue an SF.SMC request to affect its 
own terminal, fTIO:. A privileged task can issue SF.SMC to any 
terminal. 


3.3.2.13 IO.WAL - The Write All function causes the driver to pass 
all output from the buffer without interpretation. It does not 
intercept control characters. Lines are neither wrapped around (if 
input/output wrap-around has been selected) nor truncated (if 
wrap-around is not selected). 


IO.WAL is equivalent to IO.WLB!TF.WAL. 


3.3.2.14 IO.WBT - The Write Break Through function instructs’ the 
driver to write the buffer regardless of the I/0 status of the 
receiving terminal. If an IO.WBT is issued on a system that does not 
support IO.WBT, it is treated as an IO.WLB. 


e If another write is in progress, it finishes and the IO.WBT is 
the next write issued. The effect of this is that IO.WBTs can 
be stopped by a CTRL/S. Therefore, tasks may still want to 
time out on IO.WBT. 


e If a read is posted, the IO.WBT proceeds anyway, and an 
automatic CTRL/R is performed to redisplay any input that was 
received before the break-through write. 


e cCTRL/S and/or CTRL/O, if in effect, are canceled. 
e Characters input during a break-through write are ignored. 


An IO.WBT cannot break through another IO.WBT that is in progress or 
if a prompt is being. written by IO.RPR. In either case, the low-order 
byte of the first word of the I/O status block contains IE.RSU&377. 
The task receiving this error need only reissue the write. 


Break-through write may only be issued by a privileged task. However, 
the task does not have to be mapped to the Executive (Task Builder 
options /PR:4 or /PR:5). A task can use IO.WBT if it is built with 
the /PR:0 switch specified. The privileged MCR command BRO 
(broadcast) uses IO.WBT. 


Break-through write cannot break through a multiecho. Instead, it 
returns error code IE.RSU. When this occurs, the task should reissue 
the write request. 
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3.4 STATUS RETURNS 


Table 3-8 lists error and status conditions that are returned by the 
terminal driver. 


Upon successful completion of a read, the I/O status block contains 
data of this sort: 


HE 0 Byte 
Word 0 
2 
ret = 0 means read terminated by buffer full 
(byte count satisfied); 

ret = 15 means IS.CR: read terminated by carriage return. 
ret = 33 means IS.ESC: read terminated by an Altmode. 
ret = 233 means IS.ESQ: read terminated by an escape sequence. 
+1 is IS.SUC: the return code for successful 


completion. 


Most RSX-11M return codes are byte values: for example, IS.SUC = 1 is 
a byte value. By contrast, the three return codes IS.CR, IS.ESC, and 
IS.ESQ are word values. The low-order byte indicates successful 
completion, and the high-order byte is required to show what type of 
completion occurred. 


To test for one of these word-value ‘return codes, first test the 
low-order byte of the first word of the IOSB for the value IS.SUC. 
Then test the full word for IS.CR, IS.ESC, or IS.ESQ. (If the full 
word tests equal to IS.SUC, then its high-order byte is 0, indicating 
byte-count termination of the read.) 


The "error" return IE.EOF may be considered to indicate a _ successful 
read, because characters can be returned to the task's buffer. 


The three errors in Table 3-8 with SE.xxx codes are returned by the 
SF.GMC and SF.SMC QIOs. They are characterized by IE.AB0O&377 in the 
low-order byte of the first IOSB word. The high-order byte contains 
the error code. The second IOSB word contains an offset (starting 
from 0) to the byte in error in the QIOs stadd buffer. 


3.5 CONTROL CHARACTERS AND SPECIAL KEYS 


This section describes the meanings of special terminal control 
characters and keys for RSX-11M. Note that the driver does not 
recognize control characters and special keys during a Read All 
request (IO.RAL), and recognizes only some of them during a Read with 
Special Terminators (I0.RST). 


3-16 


IE. EOF 


IS.SUC 


IS.CR 


| Is. ESQ 
IS.PND 
IE.ABO 


IE.BAD 
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Table 3-8 
Terminal Status Returns 


Reason 


Successful completion on a read with end-of-file 


The line of input read from the terminal was 
terminated with the end-of-file character CTRL/Z. 
The second word of the I/O status block contains 
the number of bytes read before CTRL/Z was seen. 
The input buffer contains those bytes. 


Successful completion 


The operation specified in the QIO directive was 
completed successfully. If the operation involved 
reading or writing, you can examine the second word 
of the I/O status block to determine the number of 
bytes processed. The input buffer contains those 
bytes. 


Successful completion on a read 


The line of input read from the terminal was 
terminated by a carriage return. The input buffer 
contains the bytes read. 


Successful completion on a read 


The line of input read from the terminal was 
terminated by an Altmode character. The input 
buffer contains the bytes read. 


Successful completion on a read 


The line of input read from the terminal was 
terminated by an escape sequence. The input buffer 
contains the bytes read and the escape sequence. 


I/O request pending 


The operation specified in the QIO directive has 
not yet been executed. The I/O status block is 
filled with Os. 


Operation aborted 


The specified I/O operation was canceled by I0.KIL 
while in progress or while in the I/O queve. The 
second word of the IOSB shows how many bytes were 
processed before the kill took effect. Note that 
the SE.xxx error codes are characterized by IE.ABO& 
377 in the low-order byte of the first word of the 
IOSB. 


Bad parameter 


The size of the prom mpt in a read-after-prompt OI0 
is too big (that is, greater than 255 bytes on 


systems supporting variable-length buffers or 
[I a a | than 80 on systems that do not). 


(continued on next page) 


IE.DAA 


IE.DNA 


IE.DNR 


IE.IES 


IE.IFC 


IE.NOD 
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Table 3-8 (Cont.) 
Terminal Status Returns 


Device already attached 


The physical device unit specified in an I0.ATT 
function was already attached by the issuing task. 
This code indicates that the issuing task has 
already attached the desired physical device unit, 
not that the unit was attached by another task. If 
the attach specified TF.AST or TF.ESQ, these 
subfunction bits have no effect. 


Device not attached 


The physical device unit specified in an I0O.DET 
function was not attached by the issuing task. 
This code has no bearing on the attachment’ status 
of other tasks. 


Device not ready 


The physical device unit specified in the QIO 
directive was not ready to perform the desired I/0 
operation. This code is returned to indicate one 
of the following conditions: 


e A time-out occurred on the physical device unit 
(that is, an interrupt was lost). 


e An attempt was made to perform a function on a 
remote DH11 or DZ11 line without carrier 
present. (The line is hung up.) 

Invalid escape sequence 

An escape sequence was started but escape-Sequence 

syntax was violated before the sequence was 

completed. See Section 3.6.4. 

Illegal function 

A function code specified in an I/0 request was 

illegal for terminals; or, the function code 

specified was a SYSGEN option not selected for this 
system. 


Buffer aliocation failure 


System dynamic storage has been depleted, and there 


was insufficient space available to allocate an 
intermediate buffer for an input request. 


(continued on next page) 
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Table 3-8 (Cont.) 
Terminal Status Returns 


Device off line 


The physical device unit associated with the LUN 


specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not in 
the configuration. 


IE.PES Partial escape sequence 


An escape sequence was started, but read-buffer 
space was exhausted before the sequence was 
completed. See Section 3.6.4.3. 


IE.PRI Privilege violation 


In a multiuser system, a nonprivileged task either 
issued an I0.WBT or directed an SF.SMC to a 
terminal other than its own TIO:. 


TE.RSU Resource in use 


The prompt of an IO.RPR, or a break-through write, 
was in progress when an I0.WBT was issued. Reissue 
the IO.WBT later. 


IE.SPC Illegal address space 


The buffer specified for a read or write request 
was partially or totally outside the address space 
of the issuing task. Alternately, a byte count of 
0 was specified. 


SE.BIN The new value specified for a terminal 
characteristic in an SF.SMC request was not 0 or l. 
(Characteristics other than TC.TTP -- see Table 
3-5.) 


SE.NIH A terminal characteristic other than those in Table 
3-5 was named in an SF.GMC or SF.SMC request; or, 
a task attempted to assert TC.PRI. 


SE.VAL The new value specified in an SF.SMC request for 
the TC.TTP terminal characteristic was not one of 
those listed in Table 3-6, or the baud rate (speed) 
specified is not valid. 
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3.5.1 Control Characters 


A control character is input from a terminal by holding the control 
key (CTRL) down while typing one other key. Two of the control 
characters described in Table 3-9, CTRL/U and CTRL/Z, are echoed on 
the terminal as “U and “Z, respectively. Other control characters are 
recognized by the terminal driver, but are not printing characters and 
therefore are not echoed. 


Table 3-9 
Terminal Control Characters 


CTRL/C Typing CTRL/C repeatedly is the way to get a 
terminal's attention. Normally, typing CTRL/C 
causes unsolicited input on that terminal to be 
directed to the Monitor Control Routine (MCR). 
"MCR>" echoes when the terminal is ready to accept 
unsolicited input. When the unsolicited input 
completes, it is passed to MCR. 


If the last item typed on the terminal was CTRL/S 
(suspend output), then CTRL/C restarts suspended 
output and directs subsequent input to MCR. 


If the hold-screen mode option has been selected at 
SYSGEN, and if the terminal is a VT5x or VT61 in 
hold-screen mode, then typing a string of CTRL/Cs 
eventually removes the terminal from hold-screen 
mode. 


CTRL/CS are directed to a task if the task has 
attached a terminal and has specified an 
unsolicited-input-character AST. See the discussion 
on unsolicited-input-character ASTs, Section 
Oe awe eke CTRL/CS also go to a task if an IO.RAL 
(Read All) or I0.RST (Read with Special 
Terminators) is posted. 


and the terminal spaces to the next tab stop. Tabs 
at every eighth character position are simulated by 


| 

Not all CTRL/CS act to get MCR's attention. | 
| 

the terminal driver. 
t 


| | 
| 
CTRL/I Typing CTRL/I or TAB initiates a horizontal tab, 


CTRL/J Typing CTRL/J is equivalent to typing the LINE FEED 
key on the terminal. 

CTRL/K Typing CTRL/K initiates a vertical tab, and _ the 
terminal performs four line feeds. 

CTRL/L Typing CTRL/L initiates a form feed, and_ the 
terminal performs eight line feeds. Paging is not 
performed. 

CTRL/M Typing CTRL/M is equivalent to typing the carriage 


RETURN key on the terminal (see Section 3.5.2). 


{continued on next page) 
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Table 3-9 (Cont.) 
Terminal Control Characters 


Typing CTRL/O suppresses output being sent to a 
terminal by the current I/O request. For attached 
terminals, CTRL/O remains in effect, and output 
continues to be suppressed until any of the 
following occurs: 


CTRL/O 


1. The terminal is detached. 


3. Another CTRL/O character is typed. 
4. An I0.CCO, IO.WBT, or IO.RPR is processed. 


| 
2. Input is entered. 
For unattached terminals, CTRL/O suppresses output 
for only the current output buffer (generally one 
| line). 
CTRL/Q (SYSGEN option.) Typing CTRL/Q resumes’ terminal 
output previously suspended by means of CTRL/S. 


CTRL/R (SYSGEN option.) Typing CTRL/R on a terminal 
results in the echo of CR/LF followed by the 
incomplete (unprocessed) input line. Any tabs that 
were input are expanded and the effect of any 
rubouts is shown. On hard-copy terminals, CTRL/R 
allows you to verify the effect of tabs and/or 
rubouts in an input line. CTRL/R is also useful 
for CRT terminals when the automatic-cariage-return 
and CRT rubout SYSGEN options have been selected 
(see Section 3.8). For example, after rubbing out 
the leftmost character on the second displayed line 
of a wrapped input line, you will find that the 
cursor does not move to the right of the first 
displayed line. In this case, CTRL/R brings the 
input line and the cursor back together again. 


CTRL/S (SYSGEN option.) Typing CTRL/S causes’ terminal 
output to be suspended. Output is resumed by 
typing CTRL/OQ or CTRL/C. 


CTRL/U Typing CTRL/U before typing a line terminator 
causes previously typed characters to be deleted 
back to the beginning of the line. The system 
echoes this character as “U followed by a carriage 
return and a line feed. This allows you to retype 
the line. 


CTRL/Z Typing CTRL/Z indicates an end-of-file for the 
current terminal input. It signals MAC, PIP, TKB, 
and other system tasks that terminal input is 
complete and the task should exit. The system 
echoes this character as ~Z followed by a carriage 
return and a line fe ee ee eee ne Nl 
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3.5.2 Special Keys 


The ESCape, carriage RETURN, and RUBOUT keys have special significance 
for terminal input, as described in Table 3-10. A line can be 
terminated by an ESCape (or Altmode) character, by a carriage RETURN, 
by CTRL/Z, or by completely filling the input buffer (that is, by 
exhausting the byte count before a line terminator is typed). The 
Standard buffer size for a terminal can be determined by issuing a GET 
LUN INFORMATION system directive and examining Word 5 of the 
information buffer. Another way is to type the MCR command "SET 
/BUF=TI:". 


3.6 ESCAPE SEQUENCES 


Escape sequences are strings of two or more characters beginning with 
33 octal. Some terminals generate an escape sequence when a special 
key is pressed (for example, the PF1l key on the VT100). On any 
terminal, an escape sequence may be generated manually by typing 
ESCape and the appropriate following characters. 


Escape sequences provide a way to pass input to a task without 
interpretation by the operating system. This could be done with a 
number of l-character Read Alls, but escape sequences allow a neater 
way to accomplish it (they can be read with ordinary IO.RLBs). 

Most DIGITAL software currently does not employ escape sequences. The 


specifics provided here are for the benefit of users who wish to take 
advantage of escape sequences in their own tasks. 


3.6.1 Definition 
An escape sequence is defined as follows: 


ESC [int] ... [int] fin 


ESC 


The result of pressing the ESCape key, a byte (character) of 
35 (8) 


int 


An "intermediate character" in the range 40(8) to 57(8). This 
range includes the character "space" and 15 punctuation marks. 
An escape sequence may contain any number of intermediate 
characters, or none. 


fin 
A “final character" in the range 60(8) to 176(8). This range 


includes upper- and lowercase letters, numbers, and :13 
punctuation marks. 


There are four exceptions to this general definition discussed in 
Section 3.6.5. 


RETURN 


RUBOUT 
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Table 3-10 
Special Terminal Keys 


Meaning 


If escape sequences are not recognized, typing 
ESCape or Altmode signals the terminal driver that 
there is no further input on the current line. 
This line terminator allows further input on the 
same line, because the carriage or cursor is not 
returned to the first column position. 


If escape sequences are recognized, ESCape signals 
the beginning of an escape sequence. See Section 
r26% 


Typing RETURN terminates the current line and 
causes the carriage or cursor to return to the 
first column on the line. 


Typing RUBOUT deletes the last character typed on 
an input line. Only characters typed since the 
last line terminator may be deleted. Several 
characters can be deleted in sequence by typing 
SuccesSive RUBOUTs. 


The first RUBOUT echoes as aé_ backslash (\), 
followed by the character that has been deleted. 
Subsequent RUBOUTsS cause only the deleted character 
to be echoed. The next character typed that is not 
a RUBOUT causes another backslash, followed by the 
new character, to be echoed. The following example 
illustrates rubbing out ABC and then typing CBA: 


ABC\CBA\CBA 


The second backslash is not displayed if a line 
terminator is typed after rubbing out the 
characters on a line, as in the following: 


ABC\CBA 


(SYSGEN option.) At SYSGEN time you may elect to 
support a "CRT rubout" feature. This feature 
applies to a terminal only after a SET MCR 
directive has been issued: 


SET /CRT=TI: 


(Note: See Section 3.3.2.12 for another way this 
SET can be accomplished, with the SF.SMC QIO 
function.) When a RUBOUT is struck, the last typed 
character (if any) is removed ae the incomplete 
input line and backspace-space-backspace is echoed. 
If the last typed character was a tab, enough 
backspaces are issued to move the cursor to the 
character position before the tab was typed. If a 
long input line was split, or "wrapped," by the 
automatic-carriage-return option, and a RUBOUT 
erases the last character of a previous line, the 
cursor is not moved to the previous line. CTRL/R 
must be used to |__| Sontents of the incomplete input lines | the display with the 
contents of the |__| Sontents of the incomplete input lines | input line. 
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3.6.2 Prerequisites 


Two prerequisites must be satisfied before escape sequences can be 
received by a task. 


First, the task must "ask" for them by issuing an IO.ATT and invoking 
the subfunction bit TF.ESQ. 


Second, the terminal must be declared capable of generating escape 
sequences. This may be done with an MCR SET command: 


SET /ESCSEQ=TI: 


An alternative way to tell the driver that the terminal can generate 
escape sequences is by issuing the Set Multiple Characteristics QIO. 
See Section 3.3.2.13. 


If either of these prerequisites is not satisfied, the ESC character 
is treated as a line terminator. If both prerequisites are satisfied, 
then an additional feature results. CTRL/SHIFT/O (37(8)) may be used 
as an Altmode. 


This character does not act as an Altmode from a terminal that cannot 
generate escape sequences. 


3.6.3 Characteristics 


Escape sequences always act as line terminators. That is, an input 
buffer may contain other characters that are not part of an escape 
sequence, but an escape sequence always comprises the last characters 
in the buffer. 


Escape sequences are not echoed. However, if a non-CRT rubout 
sequence is in progress, it is closed with a backslash when an escape 
sequence is begun. 


Escape sequences are not recognized in unsolicited: input streams. 
Neither are they recognized in a Read with Special Terminators 
(subfunction bit TF.RST) nor in a Read All (subfunction bit TF.RAL). 


3.6.4 Escape Sequence Syntax Violations 


A violation of the syntax defined in Section 3.6.1 causes the driver 
to abandon the eScape sequence and to return an error (IE.IES). 


3.6.4.1 DEL or RUBOUT (177(8)) - The character DEL or RUBOUT is not 
legal within an escape sequence. Typing it at any point within an 
escape sequence causes the entire sequence to be abandoned and deleted 


1. An Altmode is a line terminator that does not cause the cursor. to 
advance to a new line. On terminals that cannot generate escape 
sequences, the ESCape key acts as an Altmode. So do the characters 
175(8) and 176(8), if the terminal has not been declared lowercase 
(MCR command SET /LOWER). If the terminal is lowercase, then these 
characters represent right-brace and tilde, respectively. 
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from the input buffer. Thus, use DEL or RUBOUT to abandon an _ escape 
sequence, if desired, once you have begun it. For example, if you 
enter: 

AB ESC ™ ‘DEL. “CR 


the buffer contains "AB" and the I/0 status block looks like the 


following: 
IOSB IS<CR 


3.6.4.2 Control Characters (0-37(8)) - The reception of any character 
in the range 0 to 37(8) (with four exceptions -- see footnotel) is a 
syntax violation that terminates the read with an error (IE.IES). For 
example, entering: 

ESC ! CTRL/SHIFT/O 


results in a buffer that contains these three characters and an I/O 
status block that is similar to the following: 


IOSB Lets 


3.6.4.3 Full Buffer - A syntax error results when an escape sequence 
is terminated by running out of read-buffer space, rather than by 
reception of a final character. The error IE.PES is’ returned. For 
example, after a task issues an IQ.RLB QIO with a buffer length of 2, 
and you type: 

ESC ! A 
the buffer contains "ESC !", and the I/O status block contains: 

IOSB IE.PES 


The "A" is treated as unsolicited input. 


1. Four control characters are allowed: CTRL/Q, CTRL/S, CTRL/C, and 
CTRL/O. These characters are handled normally by the operating system 
even when an eScape sequence is in progress. For example, entering: 


ESC CTRL/S A 


gives: 


HALF-DUPLEX TERMINAL DRIVER 


3.6.5 Exceptions to Escape-Sequence Syntax 


Four "final characters" that normally would terminate an escape 
sequence are treated as special cases by the terminal driver. These 
special cases exist for historical compatibility reasons. Three of 
these characters are: : (73(8)), ? (77(8)), and O (117(8)). The 
syntax for escape sequences that contain these four characters as 
intermediates is: 


ESC 3 [int] .«.. [int] fin 
ESC ? f{int] ... [int] fin 
Esc. 0 (int)... (ant) find 


int => 40-57 (8). 
fin => 60-176 (8). 
finl => 100-176 (8). 


The fourth exception to the general syntax given in Section 3.6.1 
involves the "final character" Y (131(8)). Historically (for example, 
in the VT52), ESC Y has been used to signal the cursor position. Te 
is followed by two numbers signifying column and row positions: 


ESC Y colpos rowpos 


where colpos and rowpos are both characters in the range 40-176(8). 
They represent bias-40 numbers: colpos = 40 corresponds to column 0, 
and so forth. 


3.7 VERTICAL FORMAT CONTROL 


Table 3-11 summarizes the meanings of all characters used for vertical 
format control on the terminal. Any one of these characters can be 
specified as the value of the vfc parameter in the functions I0O.WLB, 
IO.WVB, IO.WBT, I0.CCO, or IO.RPR. 


Table 3-11 
Vertical Format Control Characters 


Octal 
Value Character Meaning 


blank SINGLE SPACE - Output a line feed, print the 
contents of the buffer, and output a carriage 
return. Normally, printing immediately 


follows the previously printed line. 


the contents of the buffer, and output a 
carriage return. Normally, the buffer 


contents are printed two lines below the 


60 0 DOUBLE SPACE - Output two line feeds, print 
previously printed line. 


61 | PAGE EJECT - Output eight line feeds (or, if 
the terminal is an LA180S, output a form 
feed), print the contents of the buffer, and 


output a carriage return. 


(continued on next page) 
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Table 3-11 (Cont.) 
Vertical Format Control Characters 


ee ace OE ee 


OVERPRINT - Print the contents of the buffer 
and output a carriage return, normally 
overprinting the previous line. 


Character 


PROMPTING OUTPUT - Output a line feed and 
print the contents of the buffer. This mode 
of output is intended for use with a terminal 
on which a prompting message is output, and 
input is then read on the same line. 


| 00 null INTERNAL VERTICAL FORMAT - Print the buffer 
contents without addition of vertical format 
| | control characters. In this mode, more than 
one line of guaranteed contiguous output can 

be printed for each I/O request. 


All other vertical format control characters are interpreted as blanks 
(40(8)). 


3.8 FEATURES AVAILABLE BY SYSGEN OPTION 


A number of terminal-driver features are available as options at the 
time the RSX-11M system is generated (see the RSX-11M System 
Generation and Management Guide or RSX-11S System Generation and 
Installation Guide, aS appropriate). Some that have been mentioned 
previously in the text are: 


e All the device-specific QIO functions 


e Special keys 


CTRL/S -- Suspend output 


CTRL/Q -- Resume suspended output 


CTRL/R -- Write incomplete input buffer 


CRT rubout 


e Escape sequences 


Other features that you may select at SYSGEN time are described in the 
following sections. 


3.8.1 Automatic Carriage Return 


By SYSGEN option, all terminals in a system may be set to “wrap 
around," on input and output, after a specified number of columns. If 
this option is selected, th number of characters per lin is 
determined on a terminal-by-terminal basis. An MCR SET command is 
used to specify the wrap-around column, n: 


>SET /BUF=TI:n 
> 
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(Note that n is an octal number by default. Type an explicit decimal 
point to enter a decimal number.) After SYSGEN and before this SET has 
been done for a given terminal, the default column width is 72 
(decimal). 


The SET /BUF command used without an argument is an enguiry that 
returns the current buffer width for a terminal: 


>SET /BUF=TI: 
BUF=TI0:00072. 
> 


A task can determine the buffer width by issuing a Get LUN Information 
directive and examining word 5. 


After the SET has been done, typing the n+lst character results in a 
CR/LF being output before the n+lst character is echoed (at the 
leftmost character position of the next line). There is still only 
one input line, but it is displayed on two lines on the terminal. 


Output also wraps around after column n. This is undesirable for some 


applications. To disable wrap-around, set the buffer to some number 
greater than the terminal's column width. Output -- and input 
too -- beyond the column width will then overprint at the right 


margin. Wrap-around is also disabled when executing the I0.WAL 
function (see Section 3.10.11), because the driver does not keep track 
of the cursor's position. 


It is possible to lose track of where you are in the input buffer if 
both the automatic carriage return and the CRT rubout features have 
been selected at SYSGEN. If, while rubbing out text on a_e wrapped 
line, you rub out the first character on that line, the cursor will 
not back up to the previous’ line. In order to resynchronize the 
cursor with the contents of the incomplete input buffer, type CTRL/R 
(if this option has been selected). 


It is also possible to cause wrap-around to malfunction. This can 
occur when more than 255(10) characters are output without an 
intervening carriage return. This condition is possible because the 
driver maintains a byte location with the current cursor position; 
thus, counts greater than 255(10) are truncated, and the cursor count 
will be invalid until the next carriage return is received. 


3.8.2 Variable-Length Buffering 


If this user-transparent SYSGEN option is selected, up to 255(10) 
characters may be read from a terminal. The terminal driver allocates 
an Executive buffer the same size as the read request. 


If the variable-length option is not chosen, any number of characters 
may be read from a terminal, but a maximum of 80(10) are transferred 
to the task issuing the read request. An Executive buffer of 80(10) 
characters is always allocated. 


Note that, whether variable-length buffering is selected or not, a 
maximum of 80(1i10) characters may be directed to MCR as unsolicited 
input. 
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3.8.3 Task Buffering of Received Characters 


This user-transparent SYSGEN option causes characters read from the 
terminal to be sent directly to the reading task's buffer. With this 
option, no Executive buffer need be allocated, and the completed input 
line need not be transferred to the task's buffer. This option, 
however, does not necessarily reduce system overhead. In a mapped 
system, each character must be mapped to the task's buffer. If 
Executive buffering was used, the mapping is done once and then all 
the characters are transferred. For the half-duplex terminal driver, 
the Executive buffers only input except for the prompt output on an 
IO.RPR request. 


Task buffering may be overridden by checkpointing. If a task is 
checkpointable, an Executive buffer is allocated in the normal way and 
the task is made eligible for checkpointing by any task, regardless of 
priority, while the read proceeds. (Checkpointing only occurs when 
there is another task that can be made active.) Since 
checkpointability is a dynamic quality controlled by the task, the 
user retains control over the resource trade-off. 


3.8.4 LA30-P Support 


This option provides a l1-byte software buffer for terminal input from 
an LA30-P. Because LA30-Ps communicate with RSX-1l1M by a 
Single-buffered hardware interface, the echoing of an input character 
may block the reception of the next input character. This is because 
a character is normally discarded by the terminal driver if it is 
received before the echo of the previous character completes. The 
SYSGEN option for LA30-P support (transparent to the user) will buffer 
the second character in the software. 


This option should not be chosen at SYSGEN if there are no LA30-Ps in 
the system. 


3.9 TERMINAL INTERFACES 


This section summarizes the characteristics of the four types of 
Standard communication-line interfaces supported by RSX-11M. All four 
interfaces support parity, but RSX-11M does not. 


3.9.1 DH11 Asynchronous Serial Line Multiplexer 


The DH11 multiplexer interfaces up to 16 asynchronous serial 
communications lines for terminal use. The DH1l1 supports programmable 
baud rates. Input and output baud rates may differ; the input rate 
may be set to 0 baud, thus effectively turning off the terminal. The 
DM11-BB option may be included to provide modem control for dial-in 
lines. These lines must be interfaced by means of a full duplex modem 
(for example, in the United States, a Bell 103A or equivalent modem). 


The direct memory access (DMA) capability of the DH11l is not supported 
by the RSX-11M terminal driver. 
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3.9.2 DJ11 Asynchronous Serial Line Multiplexer 


The DJ11 multiplexer interfaces as many aS 16 asynchronous” serial 
lines to the PDP-11 for local terminal communications. The DJ11 does 
not provide a dial-in capability, but supports jumper-selectable baud 
rates. 


3.9.3 DL11 Asynchronous Serial Line Interface 


The DL11 supports a single asynchronous serial line and handles 
communication between the PDP-11l and a terminal. A number of standard 
baud rates are available to DL11 users. Four versions of the DL1l 
interface are supported by RSX-11M for terminal use: DLI11-A, DL11-B, 
DL11-C, and DL11-D. The DLI11-E is supported by the full-duplex 
terminal driver described in Chapter 2, and by the message-oriented 
communication drivers described in Chapter ll. 


3.9.4 DZ11 Asynchronous Serial Line Multiplexer 


The DZ11 multiplexer interfaces up to eight asynchronous’ serial 
communication lines for use with terminals. It supports programmable 
baud rates; however, input and output speeds must be the same. The 
DZ11 can control a full duplex modem in auto-answer mode. 


3.10 PROGRAMMING HINTS 


This section contains information relevant to users of the terminal 
driver. 


3.10.1 Terminal Line Truncation 


If automatic carriage return has not been selected at SYSGEN, and if 
the number of characters to be printed exceeds the line length of the 
physical device unit, then the terminal driver discards the excess 
characters until it receives one that instructs it to return to 
horizontal position 1. You can determine when this will happen by 
examining word 5 of the information buffer returned by the Get LUN 
Information system directive, or by typing "SET /BUF=TI:". 


3.10.2 ESCape Code Conversion 


If escape sequences are not recognized, an ESCape or Altmode character 
code of 33, 175, or 176 is converted internally to 33 before it is 
returned to the user on input. 


3.10.3 RTO2-C Control Function 


Because the screen of an RT02C Badge Reader and Data Entry Terminal 
holds only one line of information, special care must be taken when 
sending a control character (for example, vertical tab) to the RT02-C. 
Use IO.WAL (Write All). 
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It is advisable to read without echoing when reading a badge with the 
RTO2-C. Use IO. RAL or I0O.RNE, and then write the received 
information. 


3.10.4 Checkpointing During Terminal Input 


If checkpointing during terminal input was selected as a SYSGEN 
option, a checkpointable task is stopped (and therefore eligible to be 
checkpointed) when trying to read. Therefore, a stratagem such as 
issuing a read followed by a mark-time does not work. The intent 
might be to time out the read if input is not received in a reasonable 
length of time. But the mark-time is not issued until the read 
completes. 


You can circumvent this behavior by disabling checkpointing for the 
read. This is not a desirable solution because it forces a task to 
remain in memory during the entire read. This defeats the purpose of 
selecting the checkpoint-during-terminal-input option. 


3.10.5 Time Required for IO.KIL 


An IO.KIL request may take up to 1 second to succeed, because an 
internal mark-time mechanism is used to generate a software interrupt 
to get into a clean state. The I/O may reach a state in which the 
kill can complete within this time (for instance, if a hardware 
interrupt is received). If not, the request is killed after 1 second. 


3.10.6 Use of IO.WVB 


We recommend that you routinely use IO.WVB, instead of I0.WLB, when 
writing to a terminal. If the write actually goes to a terminal, the 
Executive converts your IO.WVB into IO.WLB. However, if the LUN has 


been redirected to some inappropriate device -- a disk, for 
example -- using an IO.WVB will be rejected because a file is not open 
on the LUN. This prevents privileged tasks from overwriting block 


zero of the disk (the boot block). 


Note that any subfunction bits specified in the IO.WVB request (for 
example, TF.CCO, TF.WAL, or TF.WBT) are stripped off when the QIO is 
converted to an IO.WLB. 


3.10.7 Remote DH11 and DZ1l Lines 


All remote DH11 lines in a system are answered at the same baud rate. 
All remote DZ11 lines are also answered at the same rate, which may 
differ from the DH1l1 rate. These rates are specified at system 
generation. 


Before a remote DH11l or DZ11 line is answered, the driver clears 
certain of the terminal characteristics (see Table 3-5) that may have 
been set by an MCR SET command or by an SF.SMC QIO. The 
characteristics cleared are: TC.SCP, TC.ESQ, TC.HLD, TC.SMR, and 
TC.TTP. (Clearing TC.TTP means that a terminal type of "unknown" is 
returned to an SF.GMC request.) Also, buffer size is set to 73. 
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A DZ11 remote line must be declared to be remote before the terminal 
driver will correctly handle the modem. This is done with the MCR 
command SET /REMOTE=TI:. 


NOTE 


Because of the few modem signals that 
the DZ11 handles and the lack of 
interrupt support provided for those 
Signals, the DZ11 may not adequately 
handle telephone exchange requirements 
in all countries. 


3.10.8 High-Order Bit on Output 


Setting the high-order bit of an output byte causes it to be 
transmitted but not interpreted by the driver. 


3.10.9 Side Effects of Setting Characteristics 


Some of the characteristics that a task may set, or that you may set 
from a terminal, have side effects that should be noted. 


e TC.HLD -- Unexpected behavior can result from a terminal in 
hold-screen mode if its reception rate is much greater than 
its transmission rate. (The DH11l supports split baud rates.) 
In hold-screen mode the terminal sends a CTRL/S during 
reception of an output stream, when the screen is nearly full. 
Output is resumed -- another screen-full -- when you type 
SHIFT/SCROLL (the terminal generates CTRL/Q). Thus, no output 
is lost as a result of scrolling off the screen before you can 
read it. However, if the terminal's transmission rate is far 
below its reception rate, some unread output may scroll out of 
sight before the CTRL/S can be transmitted. 


A related point to note is that some terminals and interfaces 
are hardware buffered. This fact can cause obscure timing 
problems for tasks that try to implement hold-screen mode. 


e TC.SMR -- If this characteristic is asserted (that is, if 
lower-/uppercase conversion is disabled by, for example, SET 
/LOWER=TI:), the two characters 175(8) and 176 (8) are 


interpreted as [ (right-brace) and (tilde), respectively. 
If TC.SMR is not asserted, these two characters act as 
Altmodes. That is, they act as line terminators that do not 


advance the cursor to a new line. Altmodes are not echoed. 


3.10.10 Unsolicited-Input-Character ASTs for Tasks Attaching Several 
Terminals 


For a task that attaches several terminals (for example, a reentrant 
language processor), the handling of unsolicited input requires 
special care. When the terminal driver passes an unsolicited input 
character to a task, it does not pass any information about which of 
several terminals generated the character. The task must ascertain 
this for itself. 
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One solution is for the task to name uniquely the AST entry points for 
each attached terminal. Each separate AST then identifies its 
terminal before branching to a common routine that processes’ the 
unsolicited character. For example: 


ATT1s: -QLOSC. TOCATA;.20,<UICI> 
BR CONT 

ATT2Z*° -OLOSE TO,ATAy «0% 59 <U1C2> 
BR CONT 


UIC1l: MOV #1,~-(SP) 
BR UIC 

UIC2: MOV #2,-(SP) 
BR “UIC 


UTC: MOV (SP)+,INDEX 


3.10.11 Direct Cursor Control 


The terminal driver generally examines the output stream in order _ to 
keep track of the cursor's horizontal position (so that output can be 
wrapped around or discarded). Therefore, tasks that want to use 
direct cursor control should use IO.WALS. This prevents the terminal 
driver from inserting CR/LFs (that the task considers spurious) into 
the output stream. FORTRAN WRITE statements become IO.WVBs, which are 
interpreted by the driver. To prevent this, a FORTRAN task can use 
the CALL QIO routine or can issue carriage returns at frequent 
intervals (to make the driver think the cursor is always well to the 
left of the rightmost column, and therefore no CR/LFs need be emitted 
to keep the cursor on the screen). 


3.10.12 DL11 Receiver Interrupt Enable 


For hardware reasons, a DL11 is susceptible to losing receiver 
interrupt enable in its Receiver Status Register. The disabling of 
the receiver interrupt bit causes the terminal to print output 
requests but not to respond to input (for example, the terminal does 
not echo input characters). The terminal driver has no mechanism for 
recognizing the disabling. Therefore, it cannot recover. The bit 
must be reset with an MCR OPEN command, the console switch register, 
or a periodically rescheduled task. 


3.10.13 Loadable Driver Restrictions 


Checkpointing during terminal input, variable-length terminal buffer 
support, and escape sequence support require the presence of 
conditionally assembled Executive support. Tf a loadable terminai 
driver supports one of these features and the Executive does not (or 
vice versa), the best that can happen is an undefined global when’ the 
terminal driver is built. At worst, the system is corrupted. 


CHAPTER 4 


VIRTUAL TERMINAL DRIVER 


4.1 INTRODUCTION 


The virtual terminal driver supports offspring task use of virtual 
terminals in RSX-11M-PLUS systems. Virtual terminals are not physical 
hardware devices; they are actually implemented in software through 
the use of data structures created by the RSX-11M-PLUS Executive. 
Virtual terminals are created by the Executive when requested by 
parent tasks with the Create Virtual Terminal directive. Virtual 
terminals are useful in batch processing and other processing 
environments in providing noninteractive terminal I/O support for 
offspring tasks, eliminating the need for operator intervention. 


Offspring task(s) "spawned" by or "connected" to the parent task that 
created the virtual terminal can perform terminal I/O operations with 
the virtual terminal in the same manner as with physical terminals. 
Virtual terminals differ from physical terminals in that they receive 
input from or output to a program (the parent task), rather than’ from 
a keyboard or to a display (or printer), respectively. 


4.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the Get LUN [Information system 
directive (the first characteristics word) contains the following 
information for virtual terminals. A setting of 1 indicates that the 
described characteristic is true for virtual terminals. 


Bit Setting Meaning 
0 ul Record-oriented device 
L 1 Carriage-control device 
2 1 Terminal device 
3 0 File-structured device 
4 0 Single-directory device 
5 0 Sequential device 
6 0 Reserved 


s 
enreouse Seer me 


User-mode diagnostics supported 


~J 
@ 
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Bit Setting Meaning 

8 0 Massbus device 

9 0 Unit software write-locked 

10 0 Input spooled device 

11 0 Output spooled device 

12 0 Pseudo device 

3 0 Device mountable as a communications channel 
14 0 Device mountable as a FILES-11 volume 

LS 0 Device mountable 


Words 3 and 4 are undefined. Word 5 specifies the maximum byte count 
(that is, maximum buffer size) to which offspring requests will be 
truncated; this value is specified by the parent task in the Create 
Virtual Terminal system directive, as described in the RSX-11M/M-PLUS 
Executive Reference Manual. 


4.3 QIO MACRO 


Table 4-1 lists the standard and device-specific functions of the QIO 
macro that are valid for virtual terminals. 


Table 4-1 
Standard and Device-Specific QIO Functions for Virtual Terminals 


STANDARD FUNCTIONS: 


OLOSC TOSATT £< bx Attach device 
OLOSC “TOsDET pa Detach device 
OLOSG TOcK Ib ovex Cancel I/O request 
QTOSC IO.RLB,...,<stadd,size> Read logical block 


(effects IO.RLB) 


QIOSC IO.WLB,...,<stadd,size,stat> 


QIOSC IO.RVB,...,<stadd,size> Read virtual block | 
Write logical block | 


Write virtual block 
(effects IO.WLB) 


QIOSC IO.WVB,...,<stadd,size,stat> 


(continued on next page) 
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Table 4-1 (Cont.) 
Standard and Device-Specific QIO Functions for Virtual Terminals 


DEVICE-SPECIFIC FUNCTIONS: 


QIOSC IO.STC,...,<cb,sw2,swl> Set terminal characteristics 
(enable/disable intermediate 
I/O buffering, or return I/O 


completion status to 
offspring task) 
OIOSC SF.GMC,...,<stadd,size> Get multiple characteristics 
| QIOSC I0.GTS,...,<stadd,size> Get terminal support 
| QTOSC IO.RPR,...,<stadd,size,{[tmo], | Read logical block 
pradd,prsize,vfc> after prompt 
QITOSC SF.SMC,...,<stadd,size> Set multiple characteristics 
size 


The size of the data buffer in bytes (must be greater than 0). 
The buffer must be located within the addressing space of the 
parent or offspring task issuing the I/O request. 


Stadd 
The starting address of the data buffer. The address must be 


word aligned for SF.GMC, IO.GTS, and SF.SMC; otherwise, it may 
be aligned on a byte boundary. 


stat 
The I/O completion status code, specified by the parent task, 
that is issued by the virtual terminal driver in response to an 
offspring task's read request upon successful completion. 

cb 


- Characteristic bits to become set, selecting the following 
virtual terminal functions: 


cb Value Bits Set Function 
0 none Enable intermediate 
buffering in the Executive 
pool 
1 0 Return the specified 
virtual terminal I/O 


completion status to the 
requesting offspring task 


2 1 Disable intermediate 
buffering 

3 0 and 1 Return status for 
offspring write request 
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swl 
The I/O completion code for I/0 completion status. 
NOTE 
The sw2 and swl parameters are valid in 
the I0.STC function only when cb=1 or 
cb=3. 
tmo 
An optional time-out count (see below). 
vfc 
A character for vertical format control. See Table 3-11. 
pradd 
The starting address of the prompt buffer. 
prsize 


The size of the prompt buffer in bytes. The buffer must be 
located within the address space of the offspring task issuing 
the I/O request. 


4.3.1 Standard QIO Functions 


4.3.1.1 I0.ATT - This I/O function can be issued by offspring task 
tasks to attach the virtual terminal. (It is illegal for parent tasks 
to issue I0.ATT). Attaching a virtual terminal prevents’ other 
offspring tasks from executing I/0 operations with the virtual 
terminal. However, parent task I/O requests are always serviced when 
issued. 


4.3.1.2 I0.DET - This I/O function can be issued by offspring tasks 
to detach the virtual terminal, making it available for use by other 
offspring tasks connected to the same parent task. (It is illegal for 
parent tasks to issue IO.DET.) 


4.3.1.3 IO.KIL - Parent and offspring tasks can issue I0.KIL to 
cancel I/0 requests. An offspring task issuing IO.KIL can result in 
IE.ABO being returned to the parent task. 


4.3.1.4 I0.RLB, IO.RVB, IO.WLB, IO.WVB - These read and write 
functions execute requested I/O operations with virtual terminals in 
the same manner as with terminals described in Chapter 2, except as 
follows: 


1. The virtual terminal driver returns the tmo parameter of an 
offspring task's IO.RLB or I0.RVB request, or the vfc 
parameter of an offspring task's IO.WLB or IO.WVB request as 
a stack parameter on entry to the appropriate AST for the 
parent task. 
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2. The virtual terminal driver returns I/O completion status’ to 
the offspring task in response to successful completion of 
the offspring task's IO.RLB or IO.RVB request; however, the 
actual I/0 completion status values returned are specified 
for data transfers in the third parameter word of the parent 
task's IO.WLB or IO.WVB response, or in the second and third 
parameters of the parent task's I0.STC function response when 
no data transfer is desired. 


4.3.2 Device-Specific QIO Function (I0.STC) 


The I0.STC function can be issued by parent tasks to enable/disable 
offspring task 1/0 buffering in secondary pool, or to force an 
appropriate I/O completion status for an offspring task read I/0 
request when no data transfer is desired. Both of these applications 
for the I0.STC function are described as follows. 


Parent tasks can use I0.STC to enable (or disable) intermediate 
buffering in secondary pool. Intermediate buffering, when enabled, is 
performed on offspring task virtual terminal read and write requests 
when the offspring task is checkpointable. 


Thus, offspring tasks can be stopped for virtual terminal I/0 and 
checkpointed in a manner similar to that when physical terminals are 
used. Whenever the virtual terminal driver determines that 
intermediate buffering should not be used, offspring tasks that issue 
terminal requests become locked in memory until I/0 completion; 
transfers occur directly between parent task and offspring task 
buffers without intermediate buffering in secondary pool. 


In addition to the conditions that permit intermediate buffering (when 
specified), one condition can automatically disable intermediate 
buffering of the parent task. If the buffer size specified in the 
Create Virtual Terminal directive exceeds the maximum size specified 
at system generation time (512(10) maximum), intermediate buffering is 
disabled. 


The second application for IO.STC is to allow the virtual terminal 
driver to return an appropriate I/O completion status in response to 
an offspring task read request. I/0 status returned in this’ manner 
allows successful completion of the offspring task's request when the 
Parent task determines that no data transfer is desired; this 
condition can occur, for example, when no data is available for input 
to the offspring task by the virtual terminal driver. When used _ in 
this manner, the I0.STC function must include three parameters, 
<cb,sw2,swl>, as follows: 


cb 


A value of 1 is specified to indicate that the I/O completion 
status return to the offspring task is desired. 


NOTE 


If the virtual terminal is operating in full duplex mode, 
a cb value of 1 returns status for an offspring read 
request, and a cb value of 3 returns status for an 
offspring write request. 
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sw2 


This parameter is the second word returned in the I/O completion 
Status indicating the number of bytes read upon successful 
completion of an offspring task's read request. However, since 
no data transfer actually occurs, the value specified is 0; the 
byte count of 0 specified in this function is legal (and 
desired), whereas a byte count of 0O in write operations is 
illegal (and will result in an error being returned to the parent 
task). 


sw2 


This parameter specifies the status code to be returned to the 
offspring task by the virtual terminal driver in the first word 
of the I/0 completion status. This value is returned in the high 
byte anda value of +1 is returned in the low byte of the status 
word. Typical values and the status that each represent are 
listed as follows: 


Code Value Completion Status Indicated 

IS.SUC + 1 Successful completion 

IS.CR LS Read terminated by carriage 
return 

IS.ESC 33 Read terminated by an Altmode 

IS.ESQ 233 Read terminated by an escape 
sequence 


4.3.3 SF.GMC 


The Get Multiple Characteristics function returns information on 
terminal characteristics. This function can be issued by both the 
parent and the offspring tasks. The virtual terminal driver returns 
the characteristics that were set by the previous corresponding SF.SMC 
request. However, only the full duplex mode ({TC.FDX) characteristic 
affects the operation of the virtual terminal driver. The SF.GMC 
function is provided only to maintain transparency to the offspring 
task. 


Valid virtual terminal characteristics are listed in Table 4-2. 


4.3.4 I10.GTS 


The Get Terminal Support function returns a 4-word buffer of 
information specifying which features are a part of the virtual 
terminal driver. The virtual terminal driver provides the I0.GTS 
function only to maintain transparency to the offspring task. Table 
2-7 lists the options returned by the full duplex terminal driver. Of 
those listed, the virtual terminal driver returns the following: 


Word 1 -~- F1.BUF, F1.RPR, F1.UTB, and F1l.VBF 


Word 2 -- F2.SCH and F2.GCH 
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4.3.5 I0O.RPR 


The Read After Prompt (IO.RPR) function can be issued only by the 
offspring task. When the offspring task issues this function, the 
function appears to the parent task aS a separate write request 
followed by a read request. This function is described in Chapter 3. 


4.3.6 SF.SMC 


The SF.SMC function allows a task to set and reset the characteristics 
of a terminal. Both the parent and the offspring tasks may issue this 
function. The parent task may set virtual terminals to full duplex 
operation by using the SF.SMC function with the characteristics bit 
TC.FDX. When in full duplex mode, the virtual terminal driver 
attempts to process the offspring task's read and write requests 
simultaneously. In order to insure that these operations are 
overlapped, the parent task should minimize the amount of time it 
spends in AST state. 


The virtual terminal driver defaults to half duplex mode. 
Table 4-2 lists the characteristics that either the parent or _ the 


offspring task may set. 


Table 4-2 
Virtual Terminal Characteristics 


Bit Name Octal Meaning (If Asserted) Default Value 
Value 
‘ | 
0 
0 
0 


TC.FDX 64 Full duplex mode 
TC.SCP 12 Terminal is a scope 


TC.SMR 25 Uppercase conversion 
disabled 


TC .TTP 10 Terminal type 


4.4 STATUS RETURNS 


The error and status conditions listed in Tables 4-3 and 4-4 are 
returned by the virtual terminal driver described in this chapter. 
The SE.NIH error is returned by the SF.GMC and SF.SMC functions. For 
this error, the low byte of the first word in the I/O status block 
contains IE.ABO. The second word in the I/O status block contains an 
offset (starting at 0) pointing to the erroneous byte in the stadd 
buUrrer., 
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Table 4-3 
Virtual Terminal Status Returns for Offspring Task Requests 


ae Successful completion of an offspring task _ read 
request results in an I/O completion status specified 
in a parent task QIO parameter being returned. 
Typically, the status information returned simulates 
a subset of I/O returns normally produced by the 
terminal drivers described in Chapter 2. 


IS.SUC Successful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the I/0 
status block indicates the number of bytes 
transferred on a write operation. 


IE. IFC Invalid function code 


The offspring task attempted a read or a write 
function and the parent task did not specify an AST 
address in its response to. the requested I/O 
function, or the offspring task issued an I0.STC or 
other invalid function. 


IE.ABO Request terminated 


The offspring task issued IO.KIL or the parent’ task 
eliminated the virtual terminal unit. 


IE.SPC Illegal address space 


Part or all of the buffer specified for a read or 
write request was outside of the task's address 
space, or a byte count of 0 was specified. 


IE.UPN Insufficient dynamic storage 


The driver could not allocate an AST block to notify 
the parent task of an offspring task request, or the 
driver could not allocate an intermediate buffer in 
the Executive pool. 


SE.NIH A terminal characteristic other than those in Table 


4-2 was specified, or an offspring task attempted to 
assert TC.FDX. 


VIRTUAL TERMINAL DRIVER 


Table 4-4 
Virtual Terminal Status Returns for Parent Task Requests 


Reason 


Successful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the I/0 
Status block indicates the number of bytes 
transferred on a read or write operation. 


IE. EOF End of file encountered 


The I0.STC function was completed successfully. 
TE.BAD Bad parameters 
The parent task specified a buffer size that exceeded 
the system maximum specified at system generation 


time. 


task. 
IE.IFC Invalid function code 


A read, write, or IO.STC function was issued without 
a pending offspring task request. This status can 
occur if the offspring task cancels a pending read or 
write request. This function code is also returned 
; when I0.STC is issued to enable intermediate 
buffering on a virtual terminal unit whose buffer 
size, specified in the Create Virtual Terminal 
directive, exceeds the system maximum specified at 
system generation time. 


IE.DUN Device not attachable 


An IO.ATT or IO.DET function was issued by the parent 


SE.NIH A terminal characteristic other than those in Table 


4-2 was specified in an SF.GMC or SF.SMC request. 
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DISK DRIVERS 


5.1 INTRODUCTION 


The RSX-11M disk drivers support the disks summarized in Table 5-1. 
Subsequent sections describe these devices in greater detail. 


All of the disks described in this chapter are accessed in essentially 
the same manner. Up to eight disks of each type (except RXO1, RX02, 
RX50, RD51, RC25, RLO1L, RLO2, RA60, RA80, or RA81) may be connected to 
their respective controllers. Disks and other file-structured media 
are divided logically into series of 256-word blocks. 


5.1.1 RF11/RS11 Fixed-Head Disk 


The RF11 controller/RS1ll fixed-head disk provides random access’ bulk 
storage. It features fast track-switching time and a redundant set of 
timing tracks. 


5.1.2 RS03 Fixed-Head Disk 


The RSO3 (RH11-RH70 controller/RS03 fixed-head disk) is a fixed-head 
disk that offers speed and efficiency. With 64 tracks per platter and 
recording on one surface, the RSO3 has a capacity of 262,144 words. 


5.1.3 RS04 Fixed-—Head Disk 


The RSO4 (RH11-RH70 controller/RS0O4 fixed-head disk) is similar to the 
RSO3 disk and interfaces to the same controller, but provides twice 
the number of words per track by recording on both surfaces of the 
platter, and thus has twice the capacity. 


5.1.4 RP11/RPO2 or RPO3 Pack Disks 


The RP11 controller/RP02 or RPO3 pack disk consists of 20 data 
Surfaces and a moving read/write head. The RP03 has twice as many 
cylinders, and thus double the capacity of the RP0O2. Only an even 
number of words can be transferred in a read/write operation, 
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Table 5-1 
Standard Disk Devices 


Controller/ Bytes/ Decimal 
Drive Secs Trks Cyls Drive Blocks 


RF11/RS11 1800 =e 1 128 524,288 1024 
ter | 3600 641 1 64 524,288 1024 
RHXX/RSO4 3600 641 1 64 1,048,576 2048 
RPLLE/RPRO2 2400 10 20 200 20,480,000 40,000 
RP11C/RPO03 2400 10 20 400 40,960,000 80,000 
RHXX/RMO2 2400 32 5 823 67,420,160] 131,680 
RHXX/RMO3 3600 32 5 823 67,420,160] 131,680 
RH70/RMO5 3600 32 19 823 256,196,608) 500,384 
RH11/RP04,RP05| 3600 22 19 411 87,960,576 | 171,798 
RH70/RPO6 3600 22 19 815 174,423,040| 340,670 
RH70/RPO7 3600 50 32 6302 |516,096,000 |1,008,000 
RH70/RM80 3600 31 14 5592 |124,214,272| 242,606 
RK11/RK05 1500 12 2 200 2,457,600 4800 
RL11/RLO1 2400 403 2 256 5,242,880 10,240 
RL11/RLO2 2400 403 2 512 10,485,760 20,480 
RK611/RK06 2400 22 | 3 411 13,888,512 27,126 
RK611/RKO7 2400 22 | 3 815 27,810,800 53,790 
RX11/RXOL 360 264 1 77 256,256 494 
RX211/RX02 360 264 1 77 512,512 988 
UDA50/RA80 3600 31 14 546 121,325,568| 236,964 
UDA50/RA81 | 3600 51 14 1248 456,228,864| 891,072 
| URRBO7 BRE er 42 4 2382 204,890,112 co 
| RC25 2850 26,061,824 50,902 


10,027,008 


19,584 


409,600 800 


1. The RSO3 has 64 words per sector; the RSO4 has 128 
words/sector. 


2. The RPO7 and the RM80 each have two additional CE cylinders. 
3. The RLO1 and RLO2 each have 128 words per sector. 
4. The RX01 has 64 words per sector; the RX02 has 128 words per 


sector. 
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5.1.5 RM0O2/RM03/RMO5/RM80 Pack Disk 


The RMO2/RM03, RMO5, and RM80 are MASSBUS disk drives and adapters 
that use the existing MASSBUS controller. With a single head per 
surface, they provide a 1.2 megabyte-per-second data transfer rate. 
The RMO3, RMO5, and RM80 are used with the RH70 controller on 
PDP-11/70 systems. All other systems use the RMO2 with the RH11 
controller. 


5.1.6 RPO4, RPO5, RPO6 Pack Disks 


The RP04 or RPOS5 (RH11-RH70 controller/RP04 or RPO5 pack disk) pack 
disks consist of 19 data surfaces and a moving read/write head. Both 
offer large storage capacity with rapid access time. The RPO06 pack 
disk has approximately twice the capacity of the RPO4 or RPOS. The 
RPO7 fixed-media disk has approximately 3 times the capacity of the 
RPO6. 


5.1.7 RK11/RKO5 or RKOSF Cartridge Disks 


The RK11 controller/RKO05 DECpack cartridge disk is an economical 
storage system for medium-volume, random access’ storage. The 
removable disk cartridge offers the flexibility of large off-line 
capacity with rapid transfers of files between on- and off-line units 
without necessitating copying operations. The RKO5F has twice the 
storage capacity of the RKO5 and has a fixed (nonremovable) disk 
cartridge. 


5.1.8 RL11/RLO1 or RLO2 Cartridge Disk 


The RLO1l is a low-cost, single-head per surface disk with a burst data 
transfer rate of 512 kilobytes per second. The storage capacity of 
the RLO2 is twice that of the RLOl. 


5.1.9 RK611/RK06 or RKO7 Cartridge Disk 


The RK611 controller/RK06 cartridge disk is a removable, random 
access, bulk-storage system with three data surfaces. The storage 
capacity is 6,944,256 words per pack. The system, expandable to eight 
drives, is suitable for medium to large systems. 


The RK611 controller/RKO7 cartridge disk is generally similar to the 
RK611/RK06, except storage capacity is increased to approximately 
13,905,400 words per pack. Both RKO6 and RKO7 disks can use the same 
RK611 controller; mixing RKO6 and RKO7 disks on the same controller 
is permitted. 
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5.1.10 RX11/RX01 Flexible Disk 


The RX11 controller/RX01 flexible disk is an economical storage system 
for low-volume, random access storage. Data is stored in twenty-six 
64-word sectors per track; there are 77 tracks per disk. Data may be 
accessed by physical sector or logical block. If logical or virtual 
block I/O is selected, the driver reads four physical sectors. These 
sectors are interleaved to optimize data transfer. The next logical 
sector that falls on a new track is skewed by six sectors to allow for 
track-to-track switch time. Physical block 1/0 provides no 
interleaving or skewing and provides access to all 2002 sectors on the 
disk. Logical or virtual I/O starts on track 1 and provides access to 
494 logical blocks. 


5.1.11 RX211/RX02 Flexible Disk 


The RX211 controller/Rx02 flexible disk is an economical storage 
system for low-volume, random access’ storage. It is capable of 
operating in either an industry-standard, single-density mode (as 
stated for the RX11/RX01 flexible disk), or a double-density mode (not 
industry standard). In the single-density mode, each drive can store 
data exactly as stated in Section 5.1.10. In the double-density mode, 
data is stored in twenty-six 128-word sectors per track; there are 77 
tracks per disk. The RX211/RX02 operating in the single-density mode 
can read disks written by an RX11/RX01 flexible disk system. In 
addition, disks written by the RX211/RX02 operating in the 
single-density mode can be read by the RX11/RX01 flexible disk system. 


5.1.12 ML-1l1 Disk Emulator 


The ML-l1l is a fast, random access, block-mode MOS memory system. The 
RSX-11M and RSX-11M-PLUS operating systems treat the ML-11 as a disk. 
However, since it is not a disk, the statistics in Table 5-l do not 
apply. Unlike a disk, the number of bytes per drive varies. One 
ML-11 provides from 512 blocks to 8192 blocks of storage. 


5.1.13 UDA50/RA60/RA80/RA81 Disks 


The UDA controller is an intelligent disk controller, which contains a 
high-speed microprogrammed processor capable of performing all disk 
functions, including data handling, error detection and correction, 
and optimization of disk drive activity and data transfers. The types 
of drives that can be connected to the UDA50 controllers are the RA60 
disk drive, which has a removable pack, and the RA80 and RA81, both of 
which are fixed media drives. (For data capacities and rates, see 
Table 5-1.) Up to four of these drives can be connected to a UDA, in 
any desired combination. 


The UDA controller also has two addressable registers in the I/O page 
that are used for the initialization sequence and to initiate polling 
of command packet buffers in memory. In addition, this controller is 
also capable of carrying out an extensive self-test on power-up or 
initialization. 
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5.1.14 RC25 Disk Subsystem 


The RC25 Subsystem combines, in one package, a controller and a single 
disk drive that has a removable disk and a fixed disk. These disks 
reside in the drive as two separate logical units on a single spindle. 
Their size is the same. Both are single eight-inch disks with two 
surfaces, and both disks have the same data capacity. But 
mechanically they are different: One is a removable front-loading 
cartridge disk, while the other cannot be removed from the drive. The 
drive is designed with loadable Winchester type heads. 


An additional disk drive can be added to the RC25 Disk Subsystem, 
providing a dual spindle configuration with two fixed and two 
removable disks. The added-on disk drive is a slave to the disk 
subsystem that has the controller. 


5.1.15 RD51 Fixed 5.25 Disk/RX50 Flexible 5.25 Disk 


This subsystem is designed to serve a hard(RD)/flexible(RX) disk 
combination that can be used as a mass storage medium for small 
systems. The basic configuration for this mass storage scheme is an 
RD51 fixed disk drive and an RX50 flexible dual disk drive. In this 
configuration, the RD51l is the system device and the RX50 is used as a 
data device and/or as a backup. The RX50 dual disk is addressed as 
two separate units resulting in a basic configuration of three disk 
units. Also, another RD51 can be added to increase storage capacity. 
Some of the characteristics of the RD/RX drives are given in Table 5-1 
and in the following paragraphs. 


The RD51 disk drive is a 5.25 inch fixed disk with Winchester type 
heads. It has two disks with four data surfaces. The RD51 is soft 
sectored and field formattable. The headers for each sector contain 
the sector's cylinder number, head number, and sector number. The 
sector number is the logical sector number (0-15) that reflects the 
sector interleave of the disk. 


The RX50 dual diskette drive is a compact mass storage drive with two 
access. slots. Each slot can hold a single-sided 5.25 flexible disk. 
These diskettes are firm sectored and are not field formattable. 
Every track has sectors numbered from 1to10. The two diskettes 
share the same head transport mechanism. 


5.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for disks. A bit setting of 1 indicates that the 
described characteristic is true for disks. 
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Bit Setting Meaning 
0 0 Record-oriented device 
1 0 Carriage-control device 
2 0 Terminal device 
3 1 File structured device 
4 0 Single-directory device 
5 0 Sequential device 
6 1 Mass storage device 
y X User-mode diagnostics supported (device 
dependent) 
8 X Device supports 22-bit direct addressing 
9 0 Unit software write-locked 
10 0 Input spooled device 
dB) 0 Output spooled device 
12 0 Pseudo-device 
13 0 Device mountable as a communications 
channel 
14 1 Device mountable as a FILES-11 volume 
iS i Device mountable 


Words 3 and 4 of the buffer contain the maximum logical block number. 
Note that the high byte of U.CW2 is undefined. The user should clear 
the high byte in the buffer before using the block number. For the 
RA80 disk, these two words are undefined until the device has been 
accessed at least once. Word 5 indicates the default buffer size, 
which is 512 bytes for all disks. 


5.3 QIO MACRO 


This section summarizes the standard, and device-specific QIO 
functions for disk drivers. 


5.3.1 Standard QIO Functions 


Table 5-2 lists the standard functions of the QIO macro that are valid 
for disks. 
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Table 5-2 
Standard QIO Functions for Disks 


IO.ATT,... Attach devicel 


TOs DET fe ws Detach device 


TOLRIL as Kill 1/02 


IO.RLB,...,<stadd,size,,blkh,blkl> READ logical block 

IO.RVB,...,<stadd,size,,blkh,blkl> READ virtual block 

IO.WLB,...,<Stadd,size,,blkh,blkl1> WRITE logical block 

IO.WLC,...,<stadd,size,,blkh,blk1> WRITE logical block 
followed by write 
check3 


IO.WVB,...,<stadd,size,,blkh,blkl> WRITE virtual block 


1. In RSX-11M systems, only unmounted volumes may be attached; 
in RSX-11M-PLUS systems, only volumes mounted foreign may be 
attached. Any other attempt to attach a mounted volume will 
result in an IE.PRI status being returned in the I/O status 
doubleword. 


2. In-progress disk operations are allowed to complete when 
IO.KIL is received, because they take such a short time. I/0 
requests that are queued when IO.KIL is received are killed 
immediately. An IE.ABO status is returned in the I/O status 
doubleword. 


3. Not supported on RX0O1 or RX02 flexible disks. 


Sstadd 


The starting address of the data buffer (must be on a= word 
boundary). 


size 
The data buffer size in bytes (must be even, greater than 0, and, 
for the RPO2 and RPO3, also a multiple of four bytes). 

blkh/blkl 


Block high and block low, combining to form a double-precision 
number that indicates the actual logical/virtual block address on 
the disk where the transfer starts; blkh represents the high 8 
bits of the address, and biki the low 16 bits. 
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IO.RVB and IO.WVB are associated with file operations (see _ the 
IAS/RSX-11 I/0 Operations Reference Manual). For these functions to 
be executed, a file must be open on the specified LUN if the volume 
associated with the LUN is’ mounted. Otherwise, the virtual I/0 
request is converted to a logical I/0 request using the specified 


block numbers. 


NOTE 


When writing a new file using QIOs, the 
task must explicitly issue .EXTND File 
Control System library routine calls as 
necessary to reserve enough blocks for 
the file, or the file must be initially 
created with enough blocks allocated for 
the file. In addition, the task must 
put an appropriate value in the FDB for 
the end-of-file block number (F.EFBK) 
before closing the file. (Refer to the 
-EXTND routine description in the 
IAS/RSX-11 I/o Operations Reference 
Manual.) oa 


Each disk driver supports the subfunction bit IQ.X: inhibit retry 
attempts for error recovery. The subfunction bit is used by ORing it 
into the desired QIO; for example: 


QIOSC IO.WLB!IIQO.X,...,<stadd,size,,blkh,blkl1> 


The IQ0.X subfunction permits user-specified retry algorithms for 
applications in which data reliability must be high. 


The overlapped seek drivers for RSX-11M-PLUS support subfunction bit 
EQz O02 queue the request immediately without doing a seek (that is, 
use implied seeks). 


5.3.2 Device-Specific QIO Functions 


The device-specific functions of the QIO macro are valid for the RxX01l 
only; they are shown in Table 5-3. 


Table 5-3 
Device-Specific Functions for the 
RX01,RX02, RLO1, and RLO2 Disk Drivers 


QIOSC IO.RPB,...,<stadd,size,,,pbn>|Read physical block 


QIOSC IO.SEC,... Sense diskette characteristics 
(RX02 only) 


QIOSC IO.SMD,...,<density,,> SET media density (RX02 only) 


QIOSC IO.WDD,...,<stadd,size,,,pbn>|Write physical block (with deleted 
data mark) (RX01 and RX02 only) 


| QIOSC I0.WPB,...,<stadd,size,,,pbn>|Write physical block | 
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stadd 


The starting address of the data buffer (must be on a_ word 
boundary). 


size 
The data buffer size in bytes must be even and greater than 0). 
pbn 
The physical block number where the transfer starts (no 
validation will occur). 
density 


The media density as follows: 


Single (RX0Ol-compatible) density 


0 
2 double density 


5.3.3 Device-Specific QIO Function for the RA80 
The RA80 driver supports the device-specific QIO function shown in 


Table 5-4. 


Table 5-4 
Device-Specific QIO Function for the RA80 Disk Driver 


QTOScC IO.RLC,...,<stadd,size,,blkh,blkl> | Read Logical with Read Check 
modifier 


5.4 STATUS RETURNS 


The error and status conditions listed in Table 5-5 are returned by 
the disk drivers described in this chapter. 


Table 5-5 
Disk Status Returns 


Successful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the I/0 
status block can be examined to determine the 
number of bytes processed, if the operation 
involved reading or writing. 


(continued on next page) 
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Table 5-5 (Cont.) 
Disk Status Returns 


Reason 


I/O request pending 


The operation specified in the QIO directive has 
not yet been executed. The I/O status block is 
filled with Os. 


IS.RDD Deleted data mark read 


A deleted record was encountered while executing an 
IO.RPB function. The second word of the I/O status 
block can be examined to determine the number of 
bytes processed (RX01 and RX02 only). | 


IE.ABO Request aborted 


| An I/O request was queued (not yet acted upon by 
the driver) when an IO.KIL was issued. 


IE.ALN File already open 


The task attempted to open a file on the _ physical 
device unit associated with specified LUN, but a 
file has already been opened by the issuing task on 
that LUN. 


IE.BLK Illegal block number 


An illegal logical block number was specified. 
This code would be returned, for example, if block 
4800 were specified for an RKO5 disk, on _ which 
legal block numbers extend from 0 through 4799. 
IE.BLK would also be returned if an attempt was 
made to write on the last track of an RKO6 disk. 
(See Section 5.5.) 


Bad block error 


The disk sector (block) being read was marked as a 
bad block in the header word. 


LE..BY? Byte-aligned buffer specified 

Byte alignment was specified for a buffer, but only 
word alignment is legal for disk. Alternatively, 
the length of a buffer is not an appropriate number 
of bytes. For example, all RPO3 and RPO2 disk 
transfers must be multiples of four bytes. 


Device not ready 


The physical device unit specified in the QIO 
directive was not ready to perform the desired I/0 
operation. 


(continued on next page) 


LE. LEC 


IE.NLN 


IE.NOD 


IE.OFL 


IE.OVR 


IE. PRI 
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Table 5-5 (Cont.) 
Disk Status Returns 


Reason 


Fatal hardware error 


The controller is physically unable to reach the 
location where input/output operation is to be 
performed. The operation cannot be completed. 


Illegal function 


A function code was specified in an I/O request 
that is illegal for disks. 


File not open 


The task attempted to close a file on the physical 
device unit associated with the specified LUN, but 
no file was currently open on that LUN. 


Insufficient buffer space 


Dynamic storage space has been depleted, and there 
was insufficient buffer space available to allocate 
a secondary control block. For example, if a task 
attempts to open a file, buffer space for the 
window and file control block must be supplied by 
the Executive. This code is returned when there is 
not enough space for this operation. 


Device off line 


The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not in 
the configuration. 


Illegal read overlay request 


A read overlay was requested, and the _ physical 
device unit specified in the QIO directive was not 
the physical device unit from which the task was 
installed. The read overlay function can only be 
executed on the physical device unit from which the 
task image containing the overlays was installed. 


Privilege violation 


The task that issued the request was not privileged 
to execute that request. For disk, this code is 
returned if a nonprivileged task attempts to. read 
or write a mounted volume directly (that is, using 
IO.RLB or IO.WLB). Also, this code is returned if 
any task attempts to attach a mounted volume. 


(continued on next page) 
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Table 5-5 (Cont.) 
Disk Status Returns 
Reason 
IE.SPC Illegal address space 
The buffer specified for a read or write request 
was partially or totally outside the address space 
of the issuing task. Alternately, a byte count of 


0 was specified. 


Unrecoverable error 


been attempted upon encountering an error, the 
operation still could not be completed. For disk, 
unrecoverable errors are usually parity errors. 


ITE.WCK 


Write check error 


An error was detected during the write check 
portion of an operation. 


| oo the system's standard number of retries has 


Write-locked device 


The task attempted to write on a disk that was 
write-locked. 


When a disk I/O error condition is detected, an error is usually not 
returned immediately. Instead, RSX-11M attempts to recover from most 
errors by retrying the function as many as eight times. Unrecoverable 
errorS are generally parity, timing, or other errors caused by a 
hardware malfunction. 


5.5 PROGRAMMING HINTS 


For the RK611 controller/RKO6 or RKO7 disk, the RL11 controller/RLOl 
or RLO2 disk, RMO2 disk, RMO3 disk, RMO5 disk, RM80 disk, and RPO7 
disk, the driver write-protects the last track of the cartridge. This 
track contains the factory-recorded bad-sector file. 


CHAPTER 6 


DECTAPE DRIVER 


6.1 INTRODUCTION 


The RSX-11M DECtape driver supports the TC11-G dual DECtape controller 
with up to three additional dual DECtape transports. The TC11-G is a 
dual-unit, bidirectional, magnetic-tape transport system for auxiliary 
data storage. DECtape is formatted to store data at fixed positions 
on the tape, rather than at unknown or variable positions as on 
coventional magnetic tape. The system uses redundant recording of the 
mark, timing, and data tracks to increase reliability. Each reel 
contains 578 logical blocks. As with disk, each of these blocks can 
be accessed separately, and each contains 256 words. 


6.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characterics word) contains the following 
information for DECtapes. A bit setting of 1 indicates that the 
described characteristic is true for DECtapes. 


Bit Setting Meaning 
0 0 Record-oriented device 
Ht 0 Carriage-control device 
2 0 Terminal device 
e) 1 File structured device 
4 0 Single-directory device 
5 0 Sequential device 
6 1 Mass storage device 
7 0 User-mode diagnostics supported 
8 0 Device supports 22-bit addressing 
9 0 Unit software write-locked 
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Bit Setting Meaning 
10 0 Input spooled device 
1l 0 Output spooled device 
12 0 Pseudo device 
13 0 Device mountable as a communications 
channel 
14 1 Device mountable as a FILES-11 volume 
15 1 Device mountable 


Words 3 and 4 of the buffer contain the maximum LBN. Word 5 indicates 
the default buffer size, 512 bytes, for DECtape. 


6.3 QIO MACRO 


This section summarizes standard and device-specific QIO functions for 
the DECtape driver. 


6.3.1 Standard QIO Functions 


Table 6-1 lists the standard functions of the QIO macro that are valid 
for DECtape. 


Table 6-1 
Standard QIO Functions for DECtape 


Attach devicel 


IO.ATT, ese 


TO DE Psa e, Detach device 


LO. KI Ly. 


QIOSC IO.RLB,...,<stadd,size,,,lbn> READ logical block (forward) 


Kill 1/04 
READ virtual block (forward) | 


i OIOSC IO.WLB,...,<stadd,size,,,lbn> 


| OIOSC IO.RVB,...,<stadd,size,,,lbn> 
| WRITE logical block (forward) 


IO.WVB,...,<Sstadd,size,,,lbn> WRITE virtual block (forward) 


1. Only unmounted volumes may be attached. An attempt to attach a 
mounted volume will result in an IE.PRI status being returned in the 
I/O status doubleword. 


2. In-progress DECtape operations are allowed to complete when 
IO.KIL is received, unless the unit is not ready, because they take 
such a short time. I/O requests that are queued when I0.KIL is 
received are killed. An IE.ABO status is returned in the I/O status 
doubleword. 
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stadd 
The starting address of the data buffer (must be on a word 
boundary). 

size 


The data buffer size in bytes (must be even and greater than 0). 


lbn 


The logical block number on the DECtape where the transfer starts 
{must be in the range 0-577). 


IO.RVB and I0O.WVB are associated with file operations (see _ the 
IAS/RSX-11 I/0 Operations Reference Manual). For these functions to 
be executed, a file must be open on the specified LUN if the volume 
associated with the LUN is mounted. Otherwise, the virtual I/0 
request is converted to a logical I/O request using the specified 
block numbers. 


6.3.2 Device-Specific QIO Functions 
The device-specific functions of the QIO0 macro that are valid for 


DECtape are shown in Table 6-2. 


Table 6-2 
Device-Specific Functions for DECtape 


QIOSC IO.RLV,...,<stadd,size,,,lbn> READ logical block (reverse) 


QIOSC IO.WLV,...,<stadd,size,,,lbn> WRITE logical block (reverse) 


stadd 


The starting address of the data buffer (must be on aé_ word 
boundary). 


size 


The data buffer size in bytes (must be even and greater than 0). 


lbn 


The transfer starts (must be in the range 0-577). 
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6.4 STATUS RETURNS 


The error and status conditions listed in Table 6-3 are returned by 
the DECtape driver described in this chapter. 


Table 6-3 
DECtape Status Returns 


IS.SUC Successful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the I/0 
Status block can be examined to determine the 
number of bytes processed, if the operation 
involved reading or writing. 


IS.PND I/O request pending 


The operation specified in the QIO directive has 
not yet been executed. The I/O status block is 
filled with Os. 


IE.ABO Request aborted 


An I/O request was queued (not yet acted upon by 
the driver) when an IO.KIL was issued. 


The task attempted to open a file on the _ physical 
device unit associated with the specified LUN, but 
a file has already been opened by the issuing task 
on that LUN. 


IE.BLK Illegal block number 


An illegal logical block number was specified for 
DECtape. The number exceeds 577 (1101 (8)). 


LTE.BYT Byte-aligned buffer specified 


IE.ALN File already open 
Byte alignment was specified for a buffer, but only 
word alignment is legal for DECtape. Alternately, 
the length of the buffer is not an even number of 
bytes. 


IE.DNR Device not ready 


directive was not ready to perform the desired I/0 


The physical device unit specified in the QI0 
operation. | 


Loe cee ; Illegal function 


| 


A function code was specified in an I/O request 
that is illegal for DECtape. 


(continued on next page) 
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Table 6-3 (Cont.) 
DECtape Status Returns 


IE.NLN File not open 


The task attempted to close a file on the physical 
device unit associated with the specified LUN, but 
no file was currently open on that LUN. 


IE.NOD Insufficient buffer space 

Dynamic storage space has been depleted, and there 
was insufficient buffer space available to allocate 
a secondary control block. For example, if a task 
attempts to open a file, buffer space for the 
window and file control block must be supplied by 
the Executive. This code is returned when there is 
not enough space for this operation. 


The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not in 
the configuration. 
TE.OVR Illegal read overlay request 
A read overlay was requested and the physical 
device unit specified in the QIO directive was not 
the physical device unit from which the task was 
installed. The read overlay function can only be 
executed on the physical device unit from which the 
task image containing the overlays was installed. 


| 
TE.OFL Device off line 


IE.PRI Privilege violation 


The task that issued the request was not privileged 
to execute that request. For DECtape, this code is 
returned when a nonprivileged task attempts to read 
or write a mounted volume directly (that is, 
IO.RLB, IO.RLV, IO.WLB, or I0O.WLV). Also, this 
code is returned if any task attempts to attach a 
mounted volume. 


Illegal address space 


The buffer specified for a read or write request 
was partially or totally outside the address space 
of the issuing task. Alternately, a byte count of 
0 was specified. 


(continued on next page) 
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Table 6-3 (Cont.) 
DECtape Status Returns 


IE.VER Unrecoverable error 


After the system's standard number of retries has 
been attempted upon encountering an error, the 
operation still could not be completed. For 
DECtape, this code is returned to indicate any of 
the following conditions. 


e A parity error was encountered. 


e The task attempted a forward multiblock transfer 
past block 577 (1101 (8)). 


The task attempted a backward multiblock 
transfer past block 0. 


IE.WLK Write—-locked device 


The task attempted to write on a DECtape unit that 
was physically write-locked. 


6.4.1 DECtape Recovery Procedures 


When a DECtape I/O error condition is detected, RSX-11M attempts to 
recover from the condition by retrying the function as many as five 
times. Unrecoverable errors are generally parity, mark track, or 
other errors caused by a faulty recording medium or a hardware 
malfunction. An unrecoverable error condition also occurs when a read 
or write operation is performed past the last block of the DECtape on 
a forward operation, or the first block of the DECtape on ae reverse 
operation. 


In addition to the standard error conditions, an unrecoverable error 
is reported when the "rock count" exceeds 8. The rock count is the 
number of times the DECtape driver reverses the direction of the tape 
while looking for a block number. Assume that the block numbers on a 
portion of DECtape are 99, 96, and 101, where one bit was dropped from 
block number 100, making it 96. If an I/O request is received for 
block 100 and the tape is positioned at block 99, the driver. starts 
searching forward for block 100. The first block to be encountered is 
96 and, because the driver is searching for block 100 in a_ forward 
direction and 96 is less than 100, the search continues forward. 
Block 101 is the next block and, because number 101 is greater’ than 
100, the driver reverses the direction of the tape and starts to 
search backward. The next block number in this direction is 96, and 
the direction is reversed again because 100 is greater than 96. To 
prevent the DECtape from being hung in this’ position, continually 
rocking between block numbers 96 and 100, a maximum rock count of 8 
has been established. 
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6.4.2 Select Recovery 


If the DECtape unit is in an off-line condition when the I/O function 
is performed, the message shown below is output on the operator's 
console. 


*** DTn: --— SELECT ERROR 


where n is the unit number of the drive that is currently off line. 
The user should respond by placing the unit to REMOTE. The driver 
retries the function, from the beginning, once every second. It 
displays the message once every 15 seconds until the appropriate 
DECtape unit is selected. A select error may also occur when there 
are two drives with the same unit number or when no drive has the 
appropriate unit number. 


6.5 PROGRAMMING HINTS 


This section contains information on important programming 
considerations relevant to users of the DECtape driver described in 
this chapter. 


6.5.1 DECtape Transfers 


If the transfer length on a write is less than 256 words, a partial 
block is transferred with zero fill for the rest of the physical 
block. If the transfer length on a read is less than 256 words, only 
the number of words specified is transferred. If the transfer length 
is greater than 256 words, more than one physical block is 
transferred. 


6.5.2 Reverse Reading and Writing 


The DECtape driver supports reverse reading and writing, because these 
functions speed up data transfers in some cases. A block should 
normally be read in the same direction in which it was written. If a 
block is read from a DECtape into memory in the opposite direction 
from that in which it was written, it is reversed in memory (for 
example, word 255 becomes word 0, and 254 becomes word 1). If this 
occurs, the user must then reverse the data within memory. 


6.5.3 Speed Considerations When Reversing Direction 


It is possible to reverse direction at any time while reading or 
writing DECtape. However, the user should understand that reversing 
direction substantially slows down the movement of the tape. Because 
DECtape must be moving at a certain minimum speed before reading or 
writing can be performed, a tape block cannot be accessed immediately 
after reversing direction. Two blocks must be bypassed before a read 
or write function can be executed, to give the tape unit time to build 
up to normal access speed. Furthermore, when a request is issued to 
read or write in a certain direction, the tape first begins to move in 
that direction, then starts detecting block numbers. The following 
examples illustrate these principles. 
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If a DECtape is positioned at block number 12 and the driver’ receives 
a request to read block 10 forward, the tape starts to move forward, 
in the direction requested. When block number 14 is encountered, the 
driver reverses the direction of the tape, since 14 is greater than 
10. The search continues backward, and block numbers 11 and 10 are 
encountered. Because the direction must be reversed and the driver 
requires two blocks to build up sufficient speed for reading, block 
number 9 and 8 are also bypassed in the backward direction. Then the 
direction is reversed and the driver encounters blocks 8 and 9 forward 
before reaching block number 10 and executing the read request. 


6.5.4 Aborting a Task 


If a task is aborted while waiting for a unit to be selected, the 
DECtape driver recognizes this fact within 1 second. 


CHAPTER 7 


DECTAPE II DRIVER 


7.1 INTRODUCTION 


The DECTAPE II (TU58) driver supports TU58 system hardware, providing 
low-cost, block-replaceable mass storage. 


7.1.1 TU58 Hardware 


Each TU58 DECTAPE II system consists of one or two TU58 cartridge 
drives, one tape drive controller, and one DLll-type serial line 
interface. Each TU58 drive functions as a random access, 
block-formatted mass storage device. Each tape cartridge is capable 
of storing 512(10) blocks of 512(10) bytes each. Access time averages 
10 seconds. All I/O transfers (commands and data) occur by means of 
the serial line interface at serial transmission rates of 9600 bps. 
All read and write check operations are performed by the controller 
hardware using a 16-bit checksum. The controller performs up to eight 
attempts to read a block, as necessary, before aborting the read 
operation and returning a hard error; however, whenever more than one 
read attempt is required for a successful read, the driver is notified 
in order to report a soft error message to the error logger. 


7.1.2 TUS58 Driver 


The TUS58 driver communicates with the TU58 hardware by means of a 
serial line interface (DL11); no other interface is required. All 
data and command transfers between the PDP-1l system and the TU58 are 
done with programmed I/O and interrupt-driven routines; NPRs are not 
supported. 


7.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for the TU58. A bit setting of 1 indicates that the 
described characteristic is true for this device. 
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Bit Setting Meaning 
0 0 Record-oriented device 
1 0 Carriage-control device 
2 0 Terminal device 
3 1 File-structured device 
4 0 Single-directory device 
5 0 Sequential device 
6 ns Mass Storage device 
i; 1 User-mode diagnostics supported 
8 0 Device supports 22-bit direct addressing 
9 0 Unit software write-locked 
10 0 Input spooled device 
dk 0 Output spooled device 
i 0 Pseudo device 
13s 0 Device mountable as a communications channel 
14 1 Device mountable as a FILES-11 volume 
1S He Device mountable 


Words 3 and 4 of the buffer are a double-precision number specifying 
the total number of blocks on the device; this value is 512(10) 
blocks. Word 5 indicates the default buffer size, which is 512(10) 
bytes. 


7.3 QI0 MACRO 


This section summarizes standard and device-specific QIO functions for 
the TU58. 


7.3.1 Standard QIO Functions 


Table 7-1 lists the standard QIO system directive functions of the QIO 
macro that are valid for the TU58. 
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Table 7-1 
Standard QIO Functions for the TU58 


QIOSC TOGAT Tacs Attach device 

| QIOSC LOSDET) «sce Detach device 

| QIO$C IO.KIL,... Cancel I/O requestsl 
QIO$c IO.RLB,...,<stadd,size,,,lbn> READ logical block 
QOIOScC IO.WLB,...,<Stadd,size,,,lbn> WRITE logical block 


1. In-progress operations are allowed to complete when I0.KIL 
is received. I/O requests that are queued when IO.KIL is 
received are killed. 

stadd 
The starting address of the data buffer (must be on a word 
boundary). 

size 


The data buffer size in bytes (must be even and greater than 0). 


lbn 


The logical block number on the cartridge tape where the data 
transfer starts (must be in the range of 0-777). 


7.3.2 Device-Specific QIO Functions 


The device-specific QIO system directive functions that are valid for 
the TU58 are shown in Table 7-2. 


Table 7-2 
Device-Specific QIO Functions for the TU58 


IO.WLC,...,<Stadd,size,,,,lbn> | WRITE logical block with check 


IO.RLC,...,<stadd,size,,,,lbn> | READ logical block with check 


IO.BLS!IQ.UMD,...,<lbn> POSITION tape 


IO. DGN!TOQ.UM 


wear pF eee 
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stadd 


The starting address of the data buffer (must be on a_ word 
boundary). 


size 


The data buffer size in bytes (must be even and greater than 0). 


lbn 


The logical block number on the cartridge tape where the data 
transfer starts (must be in the range of 0-777). 


Additional details for device-specific QI0O functions are provided in 
the following paragraphs. 


7.3.2.1 I0O.WLC - The IO.WLC function writes the specified data onto 
the tape cartridge. A checksum verification is then performed by 
reading the data just written; data is not returned to the task 
issuing the function. An appropriate status, based on the checksum 
verification, is returned to the issuing task. 


7.3.2.2 I0.RLC - The IO.RLC function reads the tape with an increased 
threshold in the TU58's data recovery circuit. This is done as a 
check to insure data read reliability. 


7.3.2.3 I0.BLS - The IO.BLS function is used for diagnostic purposes 
to position the tape to the specified logical block number. If you 
specify IO.BLS, you must use the IQ.UMD subfunction (see Chapter 1). 


7.3.2.4 I0.DGN - The IO.DGN function is used for diagnostic purposes 
to execute the TU58's internal (firmware) diagnostics. Appropriate 
status information is returned to the issuing task by the I/0 status 
block. If you specify I0.DGN, you must use the IQ.UMD subfunction 
(see Chapter 1). 


7.4 STATUS RETURNS 


Table 7-3 lists the error and status conditions that are returned by 
the TU58 driver. 
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Table 7-3 
TU58 Driver Status Returns 


IS.SUC Successful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the I/0 
Status block can be examined to determine the number of 
bytes processed, if the operation involved reading or 
writing. 


IE.DNR Device not ready 


The physical device unit specified in the QIO directive 
was not ready to perform the desired I/O operation. 


IE.IFC Tllegal function 


illegal for the TU58. 
Fatal hardware error 
IE.TMO Time-out error 


The TU58 failed to respond to a function within the 
normal time specified by the driver. 


IE.VER 


A function code was specified in an I/O request that is 
IE.FHE 
Unrecoverable error 

After the system's standard number of retries (8) has 
been attempted upon encountering an error, the operation 
still could not be successfully completed. 


IE.WLK Cartridge write-locked 


The task attempted to write on a tape cartridge that is 
physically write-locked. 


CHAPTER 8 


MAGNETIC TAPE DRIVERS 


8.1 INTRODUCTION 


RSX-11M and RSX-11M-PLUS support a variety of magnetic tape devices. 
Table 8-1 summarizes these devices and subsequent sections describe 
them in greater detail. 


Programming for magtape is quite similar to programming for the 
magnetic tape cassette (see Chapter 9). Unlike cassette, however, 
magtape can handle variable-length records and allows the user to 
select a parity mode. 


8.1.1 TE10/TU10/TSO3 Magnetic Tape 


The TE1O/TU1O/TSO3 consists of a TM1l1l controller with a TE10, TU1O, or 
TSO3 transport. It is a low-cost, high-performance system for serial 
storage of large volumes of data and programs in an 
industry-compatible format. All recording is nonreturn-to-zero, 
inverted (NRZI). 


8.1.2 TE16/TULE/TU45/TU77/TU78 Magnetic Tape 


The TE16/TU16/TU45/TU77/TU78 consists of an RH11/RH70 controller, a 
TMO2, TM03, or M78 formatter, and a TE16/TU16/TU45/TU77/TU78 
transport. They are quite similar to the TE1O/TU1LO but are Massbus 
devices, with a common controller, a specialized formatter, and 
drives. Recording is either 800 bpi NRZI or 1600 bpi phase-encoded 
(PE) for the TE16/TU16/TU45/TU77. The TU78 records in 1600 bpi 
phase-encoded or 6250 bpi GCR modes. 


8.1.3 TS11/TU80 Magnetic Tape 


The TS1ll and TU80 are integrated subsystems. Each has a drive, a 


controller, and a formatter. The hardware is microprocessor 
controlled for all operations, including I/O transfers, tape motion, 
and so forth, and has comprehensive (internal) diagnostic test 


execution. Recording is 1600 bpi phase-encoded (PE). 
The TS1l operates in conventional start and stop mede while th TUSO 
star 


Operates at either low speed (start and stop mode) or high speed 
(streaming mode). Tape speed is microprocessor controlled. 
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8.1.4 TSVO5 Magnetic Tape 


The TSVO5 tape subsystem is a Q BUS device. It is an integrated 
subsystem with a drive, a controller, and a formatter. The hardware 
is microprocessor controlled for all operations, including 1/0 
transfers, tape motion, and so forth and has comprehensive (internal) 
diagnostic test execution. Recording is 1600 bpi phase-encoded (PE). 
The TSVO5 operates at 25 inches per second. 


Table 8-1 
Standard Magtape Devices 


Maximum Data 
Recording Density Tape Speed Transfer Rate Recording 
Devices Channels (Frames/Inch) (Inches/Second) | (Bytes/Second) Method 


TE10,TU10 9 (TE1O) For 7-channel: 36,000 
7 ox 9 (TU10) {| 200, 556, or 
800 
For 9-channel: 
800 


TE16,TU16 800 or 1600 For 800 bpi: NRZI or 
36,000 Phase 
For 1600 bpi: Encoding 
72,000 


or 1600 For 800 bpi: NRZI or 
60,000 Phase 
For 1600 bpi: Encoding 
120,000 


or 1600 For 800 bpi: NRZI or 
100,000 Phase 
For 1600 bpi: Encoding 
200,000 


800 12,000 NRZI 

1600 72,000 Phase Encoding 

1600 or 6250 For 1600 bpi: Phase Encoding 
200,000 or GCR (Group 


For 6250 bpi: Cyclical 
781,000 | Recording) 


40,0001 Phase Encoding 
160,0002 


40,000 Phase Encoding 


1. Low Speed 
2. High Speed 
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8.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for magtapes. A bit setting of 1 indicates that the 
described characteristic is true for magtapes. 


Bit Setting Meaning 


0 0 or. 1 Record-oriented device (0 if the tape is 
mounted, 1 if it is not) 


l 0 Carriage-control device 

2 0 Terminal device 

3 0 File-structured device 

4 0 or 1 Single-directory device (0 if the tape is not 
mounted, 1 if it is) 

5 1 Sequential device 

6 1 Mass storage device 

7 0 orl User-mode diagnostics supported 

8 0 or l Massbus device (set only for TE16, TU16, 


TU45, TU77, or TU78 drives interfaced by 
means of an RH70 controller)1l 


9 0 Unit software write-locked 
10 0 Input spooled device 
11 0 Output spooled device 
12 0 Pseudo device 
13 0 Device mountable as a communications 
channel 
14 0 or l Device mountable as a FILES-11 volumel 
15 0 or l Device mountablel 
Words 3 and 4 of the buffer are undefined; word 5 indicates the 


default buffer size, for magtapes 512 bytes. 


8.3 QI0O MACRO 


This section summarizes standard and device-specific QIO functions for 
the magtape drivers. 


1. SYSGEN and device-dependent characteristic. 
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8.3.1 Standard QIO Functions 
Table 8-2 lists the standard functions of the QIO macro that are valid 


for magtape. 


Table 8-2 
Standard QIO Functions for Magtape 


LOGATT pe -xie Attach device 
LOLDET § oes Detach device 
TO. KIDy «6% Cancel I/0 requests 


IO.RLB,...,<stadd,size> READ logical block 
(read tape into buffer) 


IO.RVB,...,<stadd,size> READ virtual block 
(read tape into buffer) 


IO.WLB,...,<stadd,size> WRITE logical block 
(write buffer contents to tape) 


IO.WVB,...,<Stadd,size> WRITE virtual block 
(write buffer contents to tape) 


stadd 


The starting address of the data buffer (must be on a_e word 
boundary). 


size 
The data buffer size in bytes. Size must be even, greater than 


0, and, for a write, must be at least 14 bytes. 


IO.KIL does not cancel an in progress request unless a select error 
has occurred. 


8.3.2 Device-Specific QIO Functions 


Table 8-3 lists the device-specific functions of the QIO macro that 
are valid for magtape. Additional details on certain functions appear 
below. 


8.3.2.1 I0.RLV - The data appears in the specified buffer in a 
fashion identical with IO.RLB or IO.RVB, as long as the data block has 
the same length as the buffer. 


8-4 April 1983 


MAGNETIC TAPE DRIVERS 


8.3.2.2 IO.RWD - Completion of IO.RWD means that the rewind has’ been 
initiated. Additional operations on that controller may then be 
queued. However, a request for the same unit will be queued by the 
driver until load point (BOT) is reached. 


8.3.2.3 IO.RWU - IO.RWU is normally used when operator intervention 
is required (for example, to load a new tape). The operator must turn 
the unit back on line manually before subsequent operations can 
proceed. 


Table 8-3 
Device-Specific QIO Functions for Magtape 


QIOSC IO.DSE,... Data Security Erase (TU78 only) 


QIOSC IO.EOF,... Write end-of-file mark (tape mark) 
QIOSC IO.ERS,... Erase (TE1O and TU1LO not 
supported) 


QIOSC IO.RLV,...,<stadd,size> READ logical block reverse (TE1O 
and TU1O not supported.) 


TO, RWD ps aa Rewind unit 


Rewind and turn unit off line 


IO.RWU,... 


Sense tape characteristics 


IO.SEC,. ee 


I0.SMO,...,<cb> MOUNT tape and set tape 
characteristics (Unit must be 


READY, tape at LOAD POINT.) 


IO0.SPB,...,<nbs> SPACE blocks 


SPACE files 


IO.SPF,...,<nes> 


1LOVSTCy68s.pCO> SET tape characteristics 


cb 


The characteristic bits to set. 
nbs 


The number of blocks to space past (positive if forward, 
negative if reverse). 
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nes 
The number of EOF marks to space past (positive if forward, 
negative if reverse). 

size 
The size of the stadd data buffer in bytes (must be an even 
number of bytes greater than 0). 

stadd 


The starting address of the data buffer (may be on a byte 
boundary). 


8.3.2.4 IO.ERS - Erases 3 inches of (write blank) tape, effectively 
providing an extended interrecord gap. (Not supported on TU10 and 
TE10.) 


8.3.2.5 I0O.DSE - The TU78 will erase from the current position to 
end-of-tape and then rewind the tape to beginning-of-tape. 


8.3.2.6 I0.SEC - This function returns the tape characteristics in 
the second I/O status word. The tape characteristic bits are defined 
as follows: 


Can Be Set by 
Bit Meaning When Set IO.SMO and I0.STC 


0 For TU10, 556 bpi x 
density (7-channel). 
For TE16, TU16, TU45, TU77, 
TU78, and TS1l, reserved. 


1 For TU10, 200 bpi X 
density (7-channel). 
For TE16, TU16, TU45, TU77, and 
TU78, reserved. 


For TS11, TU80, and TSVO5, 
swap byte mode (read/write). 


2 For TU10, core-dump X 
mode (7-channel, see below). 
For TE16, TU16, TS11, TU45, 
TU77, and TU78 reserved. 


3 Even parity (default is odd). x 
(Not selectable for the TS11.) 

4 Tape is past EOT. 

5 Last tape command encountered 


EOF (unless last command was 
backspace). 
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Can Be Set by 


Bit Meaning When Set IO.SMO and I0.STC 
6 Writing is prohibited. x 
‘| Writing with extended inter- x 


record gap is prohibited 
(that is, no recovery is attempted 
after write error). 


8 Select error on unit. 

9 Unit is rewinding. 

10 Tape is physically write-locked. 

11 For TE10O, TU10, and TSO3, reserved. xX 
For all other tapes, 1600 bpi density. 

12 For TU10, drive is 7-channel. 
For all other tapes, reserved. 

53 Tape is at load point (BOT). 

14 Tape is at end-of-volume (EOV). 

15 Tape is past EOV (reserved for dri- 


ver; always 0 when read by user). 


In core-dump mode (TU1O only, 800 bpi density, and 7-channel), each 
8-bit byte is written on 2 tape frames, 4 bits per frame. In other 
modes on 7-channel tape, only 6 low-order bits per byte are written. 


For the TS11, 1600 bpi density is always selected (bit 1l=1). Bit 11 
cannot be modified by either the IO.SMO or IO.STC functions. For 
drives that use the TM03 controller, this bit can be either set or 
cleared; however, once the tape is moved from the load (beginning of 
tape) position (BOT), the device driver modifies this bit to reflect 
the actual density of the tape currently mounted. You cannot change 
bit 11 once the tape is moved beyond BOT. For the TU78, bit 11 set 
indicates 1600 bpi and bit 11 clear indicates 6250 bpi. Bit 11 cannot 
be set or cleared once the tape is moved beyond BOT. 


The effect of these settings is illustrated in Figure 8-1 for the TE10 
and TU1LO, and in Figure 8-2 for the TE16, TU16, TU45, and TU77. 
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Figure 8-2 Determination of Tape Characteristics 
for the TE16/TU16/TU45/TU77 


8.3.2.7 I0.SMO - This function can be used as a combination of the 
sense (IO.SEC) and set (I10.STC) tape characteristics functions. 
Unlike IO.STC, however, the I0.SMO function requires that the unit be 
READY and the tape be at load point (BOT). If either of these 
conditions is not met, the function returns an error status code of 
IE.FHE (refer to Table 8-4). 


The IO.SMO function should be used to set the characteristics of a 
newly loaded tape. If the IE.FHE error code is returned, the tape 
drive is not on line and is not at BOT. 
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8.4 STATUS RETURNS 


The error and status conditions listed in Table 8-4 are returned by 
the magtape drivers described in this chapter. 


Table 8-4 
Magtape Status Returns 


Code Reason 


IS.SUC Successful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the I/0 
status block can be examined to determine the 
number of bytes processed, if the operation 
involved reading or writing. This code is also 
returned if nbs equals 0 in an I0.SPB function or 
if nes equals O in an IO.SPF function. 


IS.PND I/O request pending 


The operation specified in the QIO directive has 
not yet been completed. The I/O status block is 
filled with Os. 


IE.ABO Operation aborted 


The specified I/O operation was canceled by I0.KIL 
while in progress or while still in the I/O queue. 


IE.BBE Bad block 


A bad block was encountered while reading or 
writing and the error persists after nine retries. 
The number of bytes transferred is returned in the 
second word of the I/O status block. For TMll, 
IE.BBE may also indicate that a bad tape error 


| 
| 
| | 
i 
I 
| 
| | 
(BTE) has been encountered while reading or | 
spacing. 
IE.BYT Byte-aligned buffer specified 
Byte alignment was specified for a buffer, while 
only word alignment is legal for the QIO. 
Alternatively, the length of a buffer is not an 
pores number of bytes. 
TE.DAA | Device already attached 


The physical device unit specified in an I0O.ATT 
function was already attached by the issuing task. 
This code indicates that the issuing task has 
already attached the desired physical device unit, 
not that the unit was attached by another task. 


(continued on next page) 


IE.DAO 


ITE.DNR 


IE.EOF 
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Table 8-4 (Cont.) 
Magtape Status Returns 


Reason 


Data overrun 


On a read, a record exceeded the stated buffer 
size. The final portion of the buffer is checked 
for parity, but is not read into memory. 


Device not attached 


The physical device unit specified in an I0.DET 
function wasS not attached by the issuing task. 
This code has no bearing on the attachment’ status 
of other tasks. 


Device not ready 


The physical device unit specified in the QIO 
directive was not ready to perform the desired I/0 
operation. This code is returned to indicate one 
of the following conditions: 


e A time-out occurred on the physical device unit 
(that is, an interrupt was lost). 


e A vacuum failure occurred on the magtape drive. 


e While trying to read or space, the driver 
detected blank tape. 


The LOAD switch on the physical drive was 
Switched to the off position. 


The unit failed internal diagnostic tests (TS0O4 
only) 


End-of-file encountered 
An end-of-file (tapemark) was encountered. 
End-of-tape encountered 


The end-of-tape (physical end-of-volume) was 
encountered while the tape was moving in the 
forward direction. A 10-foot length of tape is 
provided past EOT to be used for writing data and 
markers, such as volume trailer labels. The IE.EOT 
code will continue to be returned in the I/O status 
block until the EOT marker is passed in the reverse 
direction. IE.EOT is not returned on a_e read 
operation. 


(continued on next page) 
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Table 8-4 (Cont.) 
Magtape Status Returns 


IE.EOV End-of-volume encountered (unlabeled tape) 
On a forward space function, the logical 


end-of-volume was encountered. An end-of-volume is 
two consecutive end-of-file marks (EOF), or a 
beginning-of-tape mark (BOT) followed by an EOF. 
The tape is normally left positioned between the 
two marks. 


IE.FHE Fatal hardware error 


Nonrecoverable hardware malfunction: e.g., magtape 
unit not READY and/or tape not at LOAD POINT when 
IO.SMO is issued. 


IE. IFC Illegal function 


An illegal function (or subfunction bit) was 
specified in a magtape I/O request. Refer also to 
Section 8.4.3. 


IE.OFL Device off line 


The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not in 
the configuration. 


TE.SPC Illegal address space 


The buffer specified for a read or write request 
was partially or totally outside the address space 
of the issuing task. For magtape, this code is 
also returned if a byte count of 0 was specified or 
if the user attempted to write a block that was 
less than 14 bytes long. 


IE.VER Unrecoverable error 


After the system's standard number of retries has 
been attempted upon encountering an error, the 
operation still could not be completed. For 
magtape, this code is returned in the case of CRC 
or checksum errors or when a tape block could not 
be read. 


TE.WLK Write-locked device 


The task attempted to write on a magtape unit that 
| waS physically write-locked. Alternatively, tape 


characteristic bit 6 was set by the software to 
| | write-lock the unit logically. | 
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After processing a QIO request, the magnetic tape driver returns two 
status words. The first word contains one of the I/O status codes 
listed in Table 8-4, 


For successful QIO execution (IS.SUC) or read requests (IE.DAO), the 
second I/O status word may contain further information. The 
operations for which this is true, and the information returned, are 
shown in Table 8-5. For all other cases this word is undefined. 


Table 8-5 
Information Contained in the Second I/O Status Word 


I/O Function Code Information Returned 


IO0.RLB Number of bytes transferred 
IO.RLV Number of bytes transferred 
IO. RVB Number of bytes transferred 
I0.SEC Tape characteristics word 
IO.SPB Number of records spaced over 
I0.SPF Number of files spaced over 
IO0.WLB Number of bytes transferred 
IO0.WVB Number of bytes transferred 


8.4.1 Select Recovery 


If a request fails because the desired unit is off line, no drive has 
the desired unit number, or has its power off, the following message 
is output on the operator's console: 


*** MTn: -- SELECT ERROR 


The unit number of the specified drive. 


The driver checks the unit for readiness and repeats the message every 
15 seconds until the requesting task is aborted or the unit is made 
available. In the latter case, the driver then proceeds with the 
request. 


8.4.2 Retry Procedures for Reads and Writes 


If an error occurs during a read (for example, vertical parity error), 
the recovery procedure depends on the type of magtape in use. Read 
errors for TE10, TU1LO, TSO3, TE16, TU16, TU45, TU77, are retried by 
backspacing one record and then rereading the record in question. If 
the error persists after nine retries, IE.VER is returned. Read 
errors for the TU78 are retried using a combination of backspacing one 
record and then rereading the record in question, rereading in the 
Opposite direction, rereading at both normal/low thresholds, and 


| Lua kan 
CcCLeaning cne cape. 
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Read errors for the TS11, TU80, and TSVO5 are retired by rereading the 
block in error a predetermined number of times. Every eighth reread, 
the block is passed by the tape cleaner blade. If the error persists 
after a predetermined number of retries, IE.VER is returned. 


Write recovery is the same for all devices. When a write operation 


1. Repositions the tape 


2. Erases three inches of tape (resulting in an extended 
interrecord gap) 


3. Retries the write operation 


If the error persists after a predetermined number of retries, IE.VER 
is returned. The requesting task can use I0.STC to prohibit writing 
with an extended interrecord gap. In this case, the tape is 
backspaced and the write is retried. 


8.4.3 Power-Fail Recovery for Magnetic Tapes 


If a power failure and/or loss of vacuum occurs on a magnetic’ tape 
drive, tape position is lost. (Note that an initial system boot 
simulates a recovery from a power failure.) Additionally, on auto-load 
drives, the tape will be positioned at BOT when the unit is turned on 
line. 


To prevent accidental destruction of data currently on tape, the 
driver maintains a power-fail status indicator. When this indicator 
is set, the driver disallows any data transfer or tape motion commands 
until a rewind (I0O.RWD), rewind unload (IO.RWU), or mount and set 
characteristics (I0.SMO) function is issued. These functions clear 
the power-fail indicator and allow all tape functions to be issued. 
It is also possible to issue the set and sense characteristics 
functions (I0.STC and IO.SEC) while the power-fail indicator is set. 
These functions, however, will not clear the bit. 


All functions other than those just described are considered illegal 
and cause the return of the IE.IFC (illegal function) error code to 
the requesting task. In situations where a tape is currently a 
mounted volume, the tape should be dismounted and then remounted 
before use. In doing this, the rewind command will be issued, thereby 
clearing the power-fail indicator. 


8.5 PROGRAMMING HINTS 
This section contains information on important programming 


considerations relevant to users of magtape drivers described in this 
chapter. 


8.5.1 Block Size 


Each block must contain an even number of bytes, at least 14 for a 
write and at most 65,534. However, tape usage is more efficient with 
a larger buffer. 
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8.5.2 Importance of Resetting Tape Characteristics 


A task that uses magtape should always set the tape characteristics to 
the proper value before beginning I/O operations. The task cannot be 
certain in what state a previous task left these characteristics. It 
is also possible that an operator might have changed the magtape unit 
selection. If the selection switch is changed, the new physical 
device unit may not correspond to the characteristics of the unit 
described by the respective unit control block. 


8.5.3 Aborting a Task 


If a task is aborted while waiting for a magtape unit to be selected, 
the magtape driver recognizes this fact within 1 second. 


If a task is aborted while waiting for a magtape unit to complete a 
space operation, the magtape driver may allow spacing to the next tape 
mark. 


8.5.4 Writing an Even-Parity Zero-NRZI 


If an even-parity 0 were written normally, it would appear to the 
drive as blank tape. It is therefore converted to 20 (8). If this 
conversion is undesirable, the user must ensure that no even-parity Os 
are output on the tape. 


8.5.5 Density Selection 


The TM03 and TM78 controllers impose the following density selection 
restriction: The user cannot mix recording densities on any volume 
associated with the controller. 


Density for write operations is selected when the tape is at the load 
(BOT) position. Density for read operations is hardware - selected 
during the first read (away from BOT); after the first read, the 
IO.SEC function can be used to determine (sense) tape density. 


8.5.6 End-of-Volume Status (Unlabeled Tape) 


The magnetic tape driver detects end-of-volume when it spaces over the 
second of two consecutive tape marks. The tape is left positioned 
between the two tape marks. 


The magnetic tape driver returns the IE.EOV status code only on space 
operations. IE.EOV is never returned by read operations. 


For the purpose of checking for end-of-volume, the driver treats 
beginning of tape (BOT) as a tape mark. Therefore, any forward space 
Operation from BOT that immediately encounters a tape mark will return 
IE.EOV. 


If a space cperation stops between two tape marks but does not space 
over the second one, the driver will return end of file rather than 
end-of-volume. Any subsequent space operation from this point that 
immediately spaces over the second tape mark will return 
end-of-volume,. 
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During I0.SPF operations, the driver considers all tape marks to be 
files except for BOT and for the second tape mark spaced over at the 
end of volume. 


Note that both IO.SPF and IO.SPB operations leave the tape positioned 
“after the tape mark in the direction of travel. 


If you want to treat two consecutive tape marks as end-of-volume on 
read operations, your application must keep track of the tape marks. 
The magnetic tape driver does not support two consecutive tape marks 
as end-of-volume on read operations. 


8.5.7 Resetting VCK Indicator 


When the tape transport status for a TS1l1l, TU80, or MTSVO5 changes 
(goes on-line or off-line), further I/O operations are inhibited. A 
deliberate I/O sequencing must occur to reset the VCK indicator and 
allow physical I/0 to proceed. This sequencing is done by issuing a 
IO.RWD or I0.SMO QIO or including /RW or /REW switches to command 
requests (such as DMP). 
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9.1 INTRODUCTION 


RSX-11M supports the TAl11 magnetic tape cassette (a TAl1l controller 
with a TU60 dual transport). Programming for cassette is quite 
Similar to programming for magtape (see Chapter 8). The TAl11 system 
is a dual-drive, reel-to-reel unit designed to replace paper tape. 
Its two drives run nonsimultaneously, using DIGITAL Proprietary 
Philips-type cassettes. 


The maximum capacity of a cassette, in bytes, is 92,000 (minus 300 per 
file gap and 46 per interrecord gap). It can transfer data at speeds 
of up to 562 bytes per second. Recording density ranges from 350 to 
700 bits ber inch, depending on tape postion. 


9.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for cassettes. A bit setting of 1 indicates that the 
described characteristic is true for cassettes. 


Bit Setting Meaning 
0 ul Record-oriented device 
Zz 0 Carriage-control device 
2 0 Terminal device 
3 0 File structured device 
4 0 Single-directory device 
5 1 Sequential device 
6 ni Mass storage device 
i 0 User-mode diagnostics supported 
8 0 Device supports 22-bit direct addressing 
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Bit Setting Meaning 
9 0 Unit software write-locked 
10 0 Input spooled device 
i 0 ‘Output spooled device 
12 0 Pseudo device 
13 0 Device mountable as a communications channel 
14 0 Device mountable as a FILES-11 volume 
15 0 Device mountable 


Words 3 and 4 of the buffer are undefined; word 5 indicates’ the 
default buffer size, for cassettes 128 bytes. 


9.3 QIO MACRO 


This section summarizes standard and device-specific QIO functions for 
the cassette driver. 


9.3.1 Standard QIO Functions 
Table 9-1 lists the standard functions of the QIO macro that are valid 


for cassette. 


Table 9-1 
Standard QIO Functions for Cassette 


Function 


O©OSC. TOZATT pes Attach device 


QIOSC IO.DET,... Detach device 


QIOSC IO.KIL,... Cancel I/O requests 


| 

QIOSC IO.RLB,...,<stadd,size> READ logical block 

(read tape into buffer) 
QIOSC IO.RVB,...,<stadd,size> READ virtual block 

(read tape into buffer) | 
QTOSC IO.WLB,...,<stadd,size> WRITE logical block 

(write buffer contents to 

tape) 
QIOSC IO.WVB,...,<stadd,size> WRITE virtual block | 


(write buffer contents to 
| | tape) | 
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stadd 
The starting address of the data buffer (may be on a byte 
boundary). 

size 


The data buffer size in bytes (must be greater than 0). 


IO.KIL does not affect in-progress requests. 


9.3.2 Device-Specific QIO Functions 
Table 9-2 lists the device-specific functions of the QIO macro that 


are valid for cassette. The section on programming hints below 
provides more detailed information about certain functions. 


9.4 STATUS RETURNS 


The error and status conditions listed in Table 9-3 are returned by 
the cassette driver described in this chapter. 


Table 9-2 
Device-Specific QIO Functions for Cassette 


LO.EOF y <%< Write end-of-file gap 
IO.RWD,... Rewind unit 
IO.SPB,...,<nbs> SPACE blocks 
IO.SPF,...,<nes> SPACE files 
nbs 
The number of blocks to space past (positive if forward, negative 
if reverse). 
nes 


The number of EOF gaps to space past (positive if forward, 
negative if reverse). 


Q 
ce) 
Qu 
a) 


IS.PND 


TE.ABO 


ITE.DAA 


IE.DAO 


IE.DNA 


IE.DNR 


CASSETTE DRIVER 


Table 9-3 
Cassette Status Returns 


Reason 


Successful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the I/0 
Status block can be examined to determine the 
number of bytes processed if the operation involved 
reading or writing, or. the number of blocks or 
files spaced if the operation involved spacing 
blocks or files. 


I/O request pending 

The operation specified in the QIO directive has 
not yet been executed. The I/O status block is 
filled with Os. 


Operation aborted 


The specified I/O operation was canceled by I0.KIL 
while still in the I/0 queue. 


Device already attached 


The physical device unit specified in an I0O.ATT 
function was already attached by the issuing task. 
This code indicates that the issuing task has 
already attached the desired physical device unit, 
not that the unit was attached by another task. 


Data overrun 


The driver was not able to sustain the data rate 
required by the TAl1 controller. 


Device not attached 


The physical device unit specified by an I0O.DET 
function was not attached by the issuing task. 
This code has no bearing on the attachment status 
of other tasks. 


Device not ready 


The physical device unit specified in the QIO 
directive was not ready to perform the desired I/0 
operation. This code is returned to indicate one 
of the following conditions: 


e The cassette has not been physically inserted. 


e The unit is off line. 


e A time-out occurred on the physical device unit 
(that is, an interrupt was lost). 


(continued on next page) 
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Table 9-3 (Cont.) 
Cassette Status Returns 


Reason 


End-of-file encountered 


An end-of-file gap was recognized on the cassette 
tape. This code is returned if an EOF gap is 
encountered during a read, or if the cassette is 
physically removed during an I/O operation. 


End-of-tape encountered 


While reading or writing, clear trailer at 
end-of-tape (EOT) was encountered. Unlike magtape, 
writing beyond EOT is not permitted on cassettes. 
This condition is always sensed on a write before 
it would be sensed on a read of the same section of 
tape. If IE.EOT is returned during a write, the 
cassette head has encountered EOT before finishing 
the writing of the last block. It is recommended 
that the user entirely rewrite the block on another 
cassette. 


Illegal function 


A function code was specified in an I/O request 
that is illegal for. cassette. 


Device off line 


The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not in 
the configuration. 


Illegal address space 


The buffer specified for a read or write request 
was partially or totally outside the address space 
of the issuing task. Alternatively, a byte count 
of 0 was specified on a transfer. 


Nonrecoverable error 


This code is returned when a block check error 
occurs (see Section 9.6.5). The cyclic redundancy 
check (CRC), a 2-byte value located at the end of 
each block, is a checksum that is tested during all 
read operations to ensure that data is read 
correctly. This is returned if a read request did 
not specify exactly the number of bytes of data in 
the record on tape. If a nonrecoverable error is 
returned, the user may attempt recovery by spacing 
backward one block and retrying the read operation. 


Write-locked device 
The task attempted to write on a cassette unit that 


was physically write-locked. This code may be 
returned after an IO.WLB, IO.WVB, or IO. EOF 


function. 
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9.4.1 Cassette Recovery Procedures 


If an error occurs during a read or write operation, the operation 
should be retried several times. The recommended maximum number of 
retries is nine for a read and three for a write because each retry 
involves backspacing, which does not always position the tape in the 
same place. More than three retries of a write operation may destroy 
previously written data. For example, to retry a write, it is best to 
space two blocks in reverse, then space one block forward. This 
insures the tape is in the proper position to rewrite the block that 
encountered the error. 


After read and write functions, the second I/O status word contains 
the number of bytes actually processed by the function. After spacing 
functions, it contains the number of blocks or files actually spaced. 


9.5 STRUCTURE OF CASSETTE TAPE 


Figure 9-1 illustrates a general structure for cassette tape. A 
different structure can be employed if the user wishes. 


Here the tape consists of blocks of data interspersed with sections of 
clear tape that serve as leader, trailer, interrecord gaps (IRGs), and 
end-of-file gaps. 


The logical end-of-tape in this case consists of a sentinel label 
record, rather than the conventional group of end-of-file gaps. Each 


file must contain at least one block. The size of each block depends 
upon the number of bytes the user specifies when writing the block. 


IRGS 


EOT 


| fe 


BOT 


free] fre -- peor] ux 
wee ee” 


a 
FILE 1 FILE 2 LEOT 
150 FEET 
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Figure 9-1 Structure of Cassette Tape 


Abbreviation Meaning 
CL Clear leader 
BOT Physical beginning-of-tape 
LPG Load point gap (blank tape written by driver 
before the first retrievable record) 
LR File label record 
REC Fixed-length record (data) 
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Abbreviation Meaning 
EOF End-of-file gap 
IRG Interrecord gap 
SLR Sentinel label record 
LEOT Logical end-of-tape 
EOT Physical end-of-tape 
CT Clear trailer 


9.6 PROGRAMMING HINTS 


This section contains information on important programming 
conSiderations relevant to users of the cassette driver described in 
this chapter. 


9.6.1 Importance of Rewinding 


The first cassette operation performed on a tape must always be a 
rewind to ensure that the tape is positioned to a known place. When 
it is positioned in clear tape, there is no way to determine whether 
it is in leader at the beginning-of-tape (BOT) or in trailer at the 
end-of-tape (EOT). 


9.6.2 End-of-File and IO.SPF 


The hardware senses end-of-file (EOF) as a time-out. When I0.SPF is 
issued in the forward direction (nes iS positive), the tape is 
positioned two-thirds of the way from the beginning of the final file 
gap. In effect, this is all the way through the file gap. When 
IO.SPF is issued in the reverse direction (nes is negative), the tape 
is positioned one-third of the way from the beginning of the final 
file gap (that is, two-thirds of the way from the beginning of the 
last file spaced). Therefore, to correctly position the tape for a 
read or write after issuing IO.SPF in reverse, the user should issue 
IO.SPB forward for one block, followed by I0.SPB in reverse for one 
block. 


9.6.3 The Space Functions, I0O.SPB and I0.SPF 


IO.SPB always stops in an IRG gap, IO.SPF in an EOF gap. Neither 
space function actually takes effect until data is encountered. For 
example, Suppose the tape is positioned in clear leader at BOT and the 
user requests that one block be spaced forward. The drive passes over 
the remaining leader until it reaches data, passes one block, and 
stops in the IRG. Similarly, if the same command is issued when the 
tape is at BOT on a blank tape or a tape containing only EOF gaps, the 
function does not terminate until EOT. 
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9.6.4 Verifying of Write Operations 


Certain errors, such as cyclic redundancy check, are detected on read 
but not write operations. Therefore, to ensure reliability of 
recording, it is recommended that the user perform a read in order to 
verify every write operation. 


9.6.5 Block Length 


The user must specify the exact number of bytes per block when 
requesting read or write operations. An attempt to read a block with 
an incorrect byte count causes an unrecoverable error (see Section 
9.4) to occur. 


9.6.6 Logical End-of-Tape 


The conventional method of signaling logical end-of-tape by multiple 
EOF gaps is inadequate for cassettes, because multiple EOF gaps are 
not distinguishable from each other. For example, two sequential EOF 
gaps would be read as three instead of two. Also spacing functions, 
since they are triggered by encountering data, can not recognize 
multiple EOF gaps. Consequently, the use of a sentinel or key record 
to signal logical end-of-tape is recommended. 


CHAPTER 10 


LINE PRINTER DRIVER 


10.1 INTRODUCTION 


The RSX-11M line printer driver supports the line printers summarized 
in Table 10-1. Subsequent sections of this chapter describe these 
printers in greater detail. 


Table 10-1 
Standard Line Printer Devices 


Controller Column Width | Character Set 
132 64 890 


LP11-cC LP14-C 


LP11-D LP14-D 132 96 650 


LP11-F LPO1-F 170-1110 


LP11-H LPO1-H 170-1110 


LPll-J | LP02-J 170-1110 


LP11-K LPO2-K 96 170-1110 
LP11-R LP04-R 132 64 1110 
LP11-S LP04-S 132 96 1110 
LP11-V LPO5-V 132 64 300 
LP11-W LPO5-W 132 96 300 
LP11-Y LP06-Y 132 64 600 
LP11-Z LP06-Z 132 96 460 
LP11-GA LP0O7 132 96 1200 
LP11-EA LP26 132 64 600 
LP11-EB LP26 132 64/96 600/420 
LP11-UA LP27 132 64/96 1200/800 
LS11 LS11 132 62 60-200 
LV11 LVO1 132 96 500 
LA180 LA180 132 96 150 
LNO1 LNOL Variable = 600 


* Software selectable fonts not supported by RSX. 
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10.1.1 LP1ll Line Printer 


The LPll is a high-speed line printer available in a variety of 
models. The LP1ll model line consists of band line printers and drum 
line printers. The drum printers are impact printers, that use one 
hammer per column and a revolving drum with uppercase and optional 
lowercase characters. The LP11-R and LP1l1-S are fully buffered models 
that operate at a standard speed of 1110 lines per minute. fThe other 
LP1l drum models have 20-character print buffers. These printers are 
therefore able to print at full speed if the printed line is no longer 
than 20 characters. Lines that exceed this maximum are printed at a 
slower rate. Forms with up to six parts may be used for multiple 
copies. The band line printers are impact printers that have a flat 
steel belt with raised metal characters on the face. The LPO7, LP26, 
and LP27 offer speeds from 420 to 1200 lines per minute. 


10.1.2 LS1ll Line Printer 


The LS1l is a medium-speed line printer. It has a 20-character print 
buffer, and lines of 20 characters or less are printed at a rate of 
200 lines per minute. Longer lines are printed at a slower rate. 
RSX-11M does not support the LS1l1l expanded character set feature. 


10.1.3 LV1l Line Printer 


The LVll is a fully-buffered, electrostatic printer-plotter that 
operates at a standard rate of 500 lines per minute. RSX-11M supports 
only the LV11 print capability, not the plotter mode. 


10.1.4 LA180 DECprinter 


The LA180 is a 180-character/sec, dot-matrix impact printer. It 
accepts multipart forms and pages of various lengths and widths. 


10.1.5 LNOl Laser Printer 


The LNO1l is a non-impact page printer that uses laser imaging combined 
with xerographic printing. This technology provides letter quality 
printing at line printer speeds with no noise. Printing is done on 
standard 8 1/2 inch by 11 inch paper at 12 pages per minute, which 
equates to 600 lines per minute. Contributing to the high print 
quality is a printer resolution of 300 by 300 dots per inch. The LNO1 
offers the speed of a line printer with the advantages of a 
phototypeset device. 


10.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for line printers. A bit setting of 1 indicates that the 
described characteristic is true for line printers. 
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Bit Setting Meaning 
0 1 Record-oriented device 
1 1 Carriage-control device 
2 0 Terminal device 
3 0 File structured device 
4 0 Single-directory device 
5 0 Sequential device 
6 0 Mass storage device 
at 0 User-mode diagnostics supported 
8 0 Device supports 22-bit direct addressing 
9 0 . Unit software write-locked 
10 0 Input spooled device 
aE 0 Output spooled device 
12 0 Pseudo device 
13 0 Device mountable as a communications channel 
14 0 Device mountable as a FILES-11 volume 
15 0 Device mountable 


Words 3 and 4 of the buffer are undefined; word 5 indicates the 
default size for the device, for line printers the width of the 
printer carriage (that is, 80 or 132). 
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10.3 QIO MACRO 


Table 10-2 lists the standard functions of the QIO macro that are 
valid for line printers. 


Table 10-2 
Standard QIO Functions for Line Printers 


TOSATT y 6 <a Attach device 

| QIOSC IO.DET,... ee device 
| QIOSC IO.KIL,... Peenees I/O requests 
QIOSC IO.WLB,...,<stadd,size,vfc> WRITE logical block 


(print buffer contents) 


QIOSC IO.WVB,...,<stadd,size,vfce> WRITE virtual block 
(print buffer contents) 


stadd 


The starting address of the data buffer (may be on a byte 
boundary). 


size 


The data buffer size in bytes (must be greater than 0). 


vfc 


A vertical format control character from Table 10-4. 
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IO.KIL does not cancel an in-progress request unless the line printer 
is in an off-line condition because of a power failure or a paper jam, 
or because it is out of paper. 


The line printer driver supports no device-specific functions. 


10.4 STATUS RETURNS 


Table 10-3 lists the error and status conditions that are returned by 
the line printer driver described in this chapter. 


Table 10-3 
Line Printer Status Returns 


IS.Suc Successful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the 
T/O status block can be examined to determine the 
number of bytes processed, if the operation 
involved writing. 


IS.PND I/O request pending 


The operation specified in the QIO directive has 
not yet been executed. The I/O status block is 
filled with Os. 


IE.ABO Operation aborted 


The specified I/0 operation was canceled while in 
progress or while in the I/O queue. 


| A function code was specified in an I/0 request 


| | that is illegal for line printers. | 


(continued on next page) 


IE.DAA Device already attached 
The physical device unit specified in an I0O.ATT 
function was already attached by the issuing task. 
This code indicates that the issuing task has 
already attached the desired physical device unit, 
| not that the unit was attached by another task. 
IE.DNA Device not attached 
| | The physical device unit specified an I0.DET 
function was not attached by the issuing task. 
This code has no bearing on the attachment status 
of other tasks. 
IE.IFC pees function 
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Table 10-3 (Cont.) 
Line Printer Status Returns 


IE.OFL Device off line 


The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not 
in the configuration. 


TE.SPC Illegal address space 


The buffer specified for a write request was 

| partially or totally outside the address space of | 
the issuing task. Alternatively, a byte count of 
0 was specified. 


10.4.1 Ready Recovery 
If any of the following conditions occur: 
e Paper jam 
e Printer out of paper 
e Printer turned off line 
e Power failure 


the driver determines that the line printer is off line, and _ the 
following message is output on the operator's console: 


***LPn: -- NOT READY 


The unit number of the line printer that is not ready. 


The driver retries the function that encountered the error condition 
from the beginning, once every second. It displays the message every 
m seconds (m is defined at SYSGEN to be a value less than 256. The 
default is 15) until the line printer is readied. If a power failure 
occurs while printing a line, the entire line is reprinted from _ the 
beginning when power is restored. 


10.5 VERTICAL FORMAT CONTROL 


Table 10-4 summarizes the meaning of all characters used for vertical 
format control on the line printer Any one of these characters can 


ee os . os aUcCLe 


be specified as the vfc parameter in an IO.WLB or IO.WVB function. 
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Table 10-4 
Vertical Format Control Characters 


SINGLE SPACE: Output a line feed, print the 
contents of the buffer, and output a carriage 
return. Normally, printing immediately 
follows the previously printed line. 


Octal 
Value 


DOUBLE SPACE: Output two line feeds, print 
the contents of the buffer, and output a 
carriage return. Normally, the buffer 
contents are printed two lines below the 
previously printed line. 


PAGE EJECT: Output a form feed, print’ the 
contents of the buffer, and output a carriage 
return. Normally, the contents of the buffer 
are printed on the first line of the next 


page. 


OVERPRINT: Print the contents of the buffer 
and perform a carriage return, normally 
overprinting the previous line. 


PROMPTING OUTPUT: Output a line feed 
then print the contents of the buffer. 


and 


INTERNAL VERTICAL FORMAT: The buffer 
contents are printed without addition of 
vertical format control characters. In this 
mode, more than one line of guaranteed 
contiguous output can be printed per I/0 
request. 


All other vertical format control characters are interpreted as blanks 
(040(8)). 


10.6 PROGRAMMING HINTS 
This section contains information on important programming 


conSiderations relevant to users of the line printer driver described 
in this chapter. 


10.6.1 RUBOUT Character 
The line printer driver discards the ASCII character code 177 during 


output, because a  RUBOUT on the LS11 printer causes a RUBOUT of the 
hardware print buffer. 


10-6 


LINE PRINTER DRIVER 


10.6.2 Print Line Truncation 


If the number of characters to be printed exceeds the width of the 
print carriage, the driver discards excess characters until it 
receives one that instructs it to empty the buffer and return to 
horizontal position 1. The user can determine that truncation will 
occur by issuing a Get LUN Information system directive and examining 
word 5 of the information buffer. This word contains the width of the 
print carriage in bytes. 


10.6.3 Aborting a Task 


If a task is aborted while waiting for the line printer to be readied, 
the line printer driver recognizes this fact within 1 second. 
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CARD READER DRIVER 


l1l.1 INTRODUCTION 


The RSX-11M card reader driver supports the CRll card reader. This 
reader is a virtually jJam-proof device that reads EIA standard 
80-column punched cards at the rate of 300 per minute. The hopper can 
hold 600 cards. This device uses a vacuum picker that provides 
extreme tolerance to damaged cards and makes card wear insignificant. 
Cards are riffled in the hopper to prevent sticking. The reader uses 
a strong vacuum to deliver the bottom card. Because it has a very 
short card track, only one card is in motion at a time. 


11.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for card readers. A bit setting of 1 indicates that the 
described characteristic is true for card readers. 


Bit Setting Meaning 
0 1 Record-oriented device 
1 0 Carriage-control device 
2 0 Terminal device 
3 0 File structured device 
4 0 Single-directory device 
5 0 Sequential device 
6 0 Mass storage device 
7 0 User-mode diagnostics supported 
8 0 Device supports 22-bit direct addressing 
9 0 Unit software write-locked 
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Bit Setting Meaning 
10 0 Input spooled device 
ume 0 Output spooled device 
12 0 Pseudo device 
13 0 Device mountable as a communications 
channel 
14 0 Device mountable as a FILES-11 volume 
5 0 Device mountable 


Words 3 and 4 of the buffer are undefined; word 5 indicates’ the 
default buffer size, which is 80 bytes for the card reader. 


11.3 QI10 MACRO 


This section summarizes standard and device-specific QIO functions for 
the card reader driver. 


11.3.1 Standard QIO Functions 
Table 11-1 lists the standard functions of the QIO macro that are 


valid for the card reader. 


Table 11-1 
Standard QOIO Functions for the Card Reader 


Format 
LOZATT 5. 5% Attach device 
LO.DET <6 Detach device 


TO. Kis 60s Cancel I/O requests 


IO.RLB,...,<stadd,size> READ logical block 
(alphanumeric) 


IO.RVB,...,<stadd,size> READ virtual block 
(alphanumeric) 


stadd 
The starting address of the data buffer (may be on a byte 
boundary). 
size 
The data buffer size in bytes (must be greater than 0). 
IO.KIL does not cancel an in-progress request unless the card reader 
is in an off-line condition because of a pick, read, stack, or hopper 


check, because of power failure, or because the RESET button has not 
been depressed. 
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11.3.2 Device-Specific QIO Functions 
The device-specific functions of the QIO macro that are valid for the 


card reader are shown in Table 11-2. 


Table 11-2 
Device-Specific QIO Function for the Card Reader 


QIOSC IO.ATA,...,<AST addr> Attach for unsolicited card AST 
QIOSC IO.RDB,...,<stadd,size> Read logical block (binary) 
stadd 


The starting address of the data buffer (may be on a byte 
boundary). 


size 


The data buffer size in bytes (must be greater than 0). 


11.4 STATUS RETURNS 


A wide variety of error conditions and recovery procedures relate to 
the use of the card reader. This section describes the three major 
ways in which the system reports error conditions. 


1. Lights and indicators on the card reader panel are turned on 
or off to indicate particular operational problems such as 
read, pick, stack, or hopper checks. Switches are available 
to turn the reader power on and off and to allow the user to 
reset after correcting an error condition. 


2. A message is output on the operator's console if operational 
checks or power problems occur. 


3. An I/O completion code is returned in the low-order byte of 
the first word of the I/O status block specified in the QIO 
macro to indicate success or failure on completion of an I/0 
function. 


The following subsections describe each of these returns in detail. 


11.4.1 Card Input Errors and Recovery 


The table included below describes all external lights and switches 
used to indicate to the operator that a hardware problem has occurred 
and must be corrected. There are two classes of hardware errors: 


e Those requiring the operator to ready the reader and try the 
operation again 


e Those requiring the op 
output stacker, to £ 
the operation again 


rator to remove the last card from the 
1 


ace it in the input hopper, and to try 
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In the first case, the card reader was unable to read the current 
card. In the second, the card was’ read incorrectly and must be 
physically removed from the output stacker. The card reader driver 
automatically restarts a read operation within 1 second after the 
cards have been replaced in the input hopper. 

Table 11-3 summarizes the functions of lights and indicators on _ the 
front panel of the card reader. It discusses common operational 


errors that might be encountered while reading cards and_ recovery 
procedures associated with these error conditions. 


11.4.2 Ready and Card Reader Check Recovery 
If any of the following conditions occur: 
e Power failure 
e Reset switch not pressed (reader off line) 


e Timing error (Two columns were read before the card reader 
driver input the first column from the card reader.) 


the driver determines that the card reader iS not ready, and _ the 
following message is output on the operator's console: 


eee CROSS NOT -READY 


When a timing error occurs, the operator can proceed with normal card 
reader operation by: 


1. Placing the card reader off line by pressing the STOP switch 


2. Removing the last card read and inserting it where it will be 
the next card read 


3. Placing the card reader on line by pressing the RESET switch 
If any of the following conditions occurs: 

e Pick error (PICK CHECK) 

e Read error (READ CHECK) 

@e Output stacker error (STACK CHECK) 

e Input hopper out of cards (HOPPER CHECK) 

e Output stacker full (HOPPER CHECK) 


the driver determines that a card reader check hasS occurred, and the 
following message is output on the operator's console: 


*** CRn: -- READ FAILURE. CHECK HARDWARE STATUS 
where n is the unit number of the card reader that is not ready. The 
operator should correct the error and press RESET: The driver 
attempts the function from the beginning, once every second. It 


displays the message once every m seconds (m is defined at SYSGEN as a 
value less than 256. The default is 15) until the card reader is 
readied. In all cases except pick error, the last card read should be 
reinserted in the input hopper, as described in Section 11.4.1. 
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Table 11-3 


Card Reader Switches and Indicators 


POWER 
Switch 


READ 
CHECK 
Indicator 


PICK 
CHECK 
Indicator 


Pushbutton 
indicator 
switch 
(alternate 
action: 
pressed 
both ON 
OFF) 


for 
and 


White light 


White light 


Controls application 
of all power to the 
card reader. 


When indicator is 


off, depressing switch 


applies power to 
reader and causes 
associated indica- 
tor to. light. 


When indicator is 
lit, depressing 
switch removes all 
power from reader and 
causes indicator to 
go out. 


When lit, this light 
indicates that the 


card just read may be. 
torn on the leading or 


trailing edges, or 
that the card may 
have punches in 
column positions 0 
or 8l. 


Because READ CHECK 
indicates an error 
condition, whenever 
this indicator is 
lit, it causes the 
card reader to stop 
operation and extin- 
guishes the RESET 
indicator. 


When lit, this light 
indicates that the 
card reader failed to 
move a card into the 
read station after 

it received a READ 
COMMAND from the 
controller. 


Stops card reader 
operation and extin- 
guishes RESET 
indicator. 


Card may have been 
read incorrectly; 
restore power if 
possible by depress- 
ing the POWER 
switch; insert the 
card again as the 
first card in the 
input hopper, and 
press the RESET 
switch; in some 
cases, it may be 
necessary to 

restart the program. 


Card was read incor- 
rectly; duplicate if 
necessary, insert 

the card again as 

the first card in the 
input hopper, and 
press the RESET 
switch. 


Card could not be 
read; press the 
RESET switch to try 
again or remove the 
cards from the input 
hopper, smooth the 
leading edges, re- 
place, and then 
press the RESET 
switch. 


(continued on next page) 
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(Cont.) 


Card Reader Switches and Indicators 


STACK 
CHECK 
Indicator 


White light 


HOPPER 
CHECK 
Indicator 


White light 


STOP 
Switch 


Momentary 
pushbutton/ 
indicator 
switch 

(red light) 


RESET 
Switch 


Momentary 
pushbutton/ 
indicator 
switch 
(green 
light) 


reeset ny nf run rr tne ERE i 


When lit, this light 
indicates that the 
previous card was not 
properly seated in 
the output stacker 
and therefore may be 
badly mutilated. 


Stops card reader 
operation and ex- 
tinguishes RESET 
indicator. 


When lit, this light 
indicates that either 
the input hopper is 
empty or that the out- 
put stacker is full. 


When depressed, 
immediately lights 
and drops the READY 
line, thereby extin- 
guishing the RESET 
indicator. Card 
reader operation then 
stops as soon as the 
card currently in the 
read station has been 
read. 


This switch has no 
effect on the system 
power; it only stops 
the current operation. 


When depressed and 
released, clears all 
error flip-flops and 
initializes card 
reader logic. Associ- 
ated RESET indicator 
lights to indicate 
that the READY. signal 
is applied to the con- 
troller. 


The RESET indicator 
goes out whenever the 
STOP switch is de- | 
pressed or whenever | 
an error indicator 
lights (READ CHECK, 
PICK CHECK, STACK 
CHECK, or HOPPER 
CHECK). 
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Card may have been 
read incorrectly and 
is not positioned 
properly in the out- 
put stacker; dupli- 
cate the card if it 
is damaged; insert 
the card again as 
the first card in 
the input hopper and- 
press the RESET. 
Switch. 


Card may have been 
read incorrectly; 
empty the stacker or 
fill the hopper; in- 
sert the card again 
as the fist card in 
the input hopper and 
press the RESET 
Switch. 
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11.4.3 I/0 Status Conditions 


The error and status conditions listed in Table 11-4 are returned by 
the card reader driver described in this chapter. 


Table 11-4 
Card Reader Status Returns 


IS.SUC 


Successful completion 


The operation specified in the QIO directive was 


completed successfully. The second word of the 
I/Q status block can be examined to determine the 
number of bytes processed, if the operation 


involved reading. 


Dynamic storage space has been depleted, and there 
was insufficient buffer space available to 
allocate a card buffer (that is, cards are read 
into a driver buffer, translated, and then moved 
lice pe eee ee the user buffer). 


IS.PND | I/O request pending 
The operation specified in the QIO directive has | 
not yet been executed. The I/O status block is 
filled with Os. 

IE.ABO Operation aborted 
The specified I/0 operation was cancelled while in 
progress or while still in the I/O queue. 

IE.DAA Device already attached 
The physical device unit specified in an I0.ATT 

| | function was already attached by the issuing task. 

IE.DNA Device not attached 
The physical device unit specified in an I0.DET 
function was not attached by the issuing task. 
This code has no bearing on the attachment status 
of other tasks. 

IE. EOF End-of-file encountered 
An end-of-file control card was recognized. 

TE <eLEC Illegal function 
A function code was specified in an I/O request 
that is illegal for card readers. 

IE.NOD Buffer allocation failure 


ee ee on next page) 
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Table 11-4 (Cont.) 
Card Reader Status Returns 


Reason 


IE.OFL Device off line 


The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not 


in the configuration. 


Illegal address space 


The buffer specified for a read request was 
partially or totally outside the address space of 
the issuing task. Alternatively, a byte count of 
0 was specified. 


11.5 FUNCTIONAL CAPABILITIES 

~The card reader driver can perform the following functions: 
1, Read cards in DECO26 format and translate to ASCII 
2. Read cards in DECO29 format and translate to ASCII 
3. Read cards in binary format 


If the QIO macro specifies the IO.RLB or IO.RVB function, the driver 
interpets all data as alphanumeric (026 or 029 format). As explained 
below, control characters indicate whether 026 or 029 is desired. 1B 
the QIO macro specifies IO.RDB, the driver interprets all data, 
including 026 and 029 control characters, as binary. 


11.5.1 Control Characters 


Table 11-5 lists the multipunched cards that the card reader driver 
recognizes as control characters. They are never transferred to the 
user's buffer or included in the count of transferred bytes in 
alphanumeric mode. In binary mode, the only control card recognized 
is binary EOF. 


DECO26 is the default translation mode when the system is 
bootstrapped. This mode remains in effect until explicitly changed by 
a control card indicating that DEC0O29 cards will follow. After 
encountering a DEC029 control card, the driver translates all cards in 
DECO29 format unless another DEC026 control card is encountered. This 
card. overrides the 029 mode specification and indicates’ that 
subsequent cards are to be translated in 026 format. Control 
characters are addressed to the card reader itself, and remain in 
effect even when the reader is attached and subsequently detached. 
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The default condition can easily be changed from DEC026 to DEC029 by 
reading a 029 control card, and then saving the system with the MCR 
SAV command. 


Table 11-5 
Card Reader Control Characters 


12-11-0-1-6-7-8-9 1 End-of-file (alphanumeric) 
12-11-0-1-6-7-8-9 | (All 8 punches in End-of-file (binary) 

the first 8 columns) 
12-2-4-8 | L 026-coded cards follow 


12-0-2-4-6-8 Li : 029-coded cards follow 


11.6 CARD READER DATA FORMATS 


The card reader reads data in either alphanumeric or binary format. 


11.6.1 Alphanumeric Format (026 and 0211) 


Table 11-6 summarizes the translation from DEC026 or DEC029 card codes 
to ASCII. 


11.6.2 Binary Format 


In RSX-11M binary format, the data are not packed, but are transferred 
exactly as read, one card column per word. Because each word has 16 
bits and each card column represents only 12, the data from the column 
are stored in the rightmost 12 bits of the word. The word's remaining 
four bits contain Os. 


11.7 PROGRAMMING HINTS 


This section contains information on important programming 
considerations relevant to users of the card reader driver described 
in this chapter. Section 11.4 contains information on operational 
error-recovery procedures that might be important from a programming 
point of view. 


11.7.1 Input Card Limitation 


Only one card can be read with a single QIO macro call. A request to 
read more than 80 bytes or columns, the length of a Ssingie card, does 
not result in a multiple card transfer. Only 80 columns are 
Processed. It is possible to read fewer than 80 columns of card input 
with a QIO read function. For example, the user can specify that only 
the first 10 columns of each card are to be read. 
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11.7.2 Aborting a Task 


If a task waiting for the card reader to be readied is aborted, the 
card reader driver recognizes this fact within 1 second. 


Table 11-6 
Translation from DEC026 or DEC029 to ASCII 


DEC026 Character DEC0O29 | DECO26 
173 12 0 12 0 : 054 0 8 3 0 8 3 
175 5 Oe a LY. 0 - 055 11 11 
SPACE 040 none none ‘ 056 128432 “8-3 
! 041 12 87/128 7 7: 057 01 01 
” 042 8 7 08 5 0 060 0 0 
# 043 8 3 0 8 6 1 061 ul 1 
$ 044 11 8 3]11 8 3 2 062 2 2 
% 045 08 4 Ors 7 3 063 3 3 
AND 046 12 a = 4 064 4 4 
: 047 8 5 8 6 5 065 5 5 
( 050 12 85/;0 8 4 6 066 6 6 
) 051 1185j),;12 8 4 7 067 7 vj 
* 052 1184/11 8 4 8 070 8 8 
+ 053 12 8 6j;,12 9 071 9 9 
: 072 8 2 11 8 2 M 115 Ld a 11 4 
: 073 11 86/0 8 2 N 116 11 5 as es 
074 12 8 4/12 8 6 O vey 4 11 6 11 6 
= 075 8 6 8 3 P 120 117 117 
> 076 0 8 6 11 8 6 Q 121 11. 8 12. 8 
? 077 | 08 7 12° 3:2 R 122 11 9 LAs 
@ 100 8 4 8 4 iS) 123 0 2 0 2 
A 101 oe 12:4 | T 124 0 3 0 3 
B 102 12 2 12 2 U p 225 0 4 0 4 
Cc 103 2 3 12 3 V | 126 05 05 
D 104 12 4 12 4 W 127 0 6 | 0 § 
E 105 12 5 12-5 Xx 130 07 0:7 
F 106 12 6 12 6 4 Pot | o 8 ‘0 8 
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CHAPTER 12 


MESSAGE-ORIENTED COMMUNICATION DRIVERS 


12.1 INTRODUCTION 


RSX-11M supports a variety of communication line interfaces: 
synchronous and asynchronous, Single-line and multiplexers, 
character-oriented and message-oriented. These are used for terminal 
communications, remote job entry, multicomputer interfaces, and 
laboratory and industrial control communications. Communications line 
interfaces can be roughly divided into two categories: 


e Terminal (character-oriented) communications devices 
e Multicomputer (message-oriented) communications devices 


Chapters 1, 2, and 3 describe the character-oriented asynchronous 
communications line interfaces used primarily £Or terminal 
communications. The Terminals and Communications Handbook contains 
more detail on these devices. This chapter describes in some detail 
the RSX-11M message-oriented synchronous and asynchronous 
communication line interfaces. These are used most frequently in 
multicomputer communications. 


Character-oriented communications devices include the DH1l, DJl1l, 
DL11-A, DL11-B/C/D, and DZ1l interfaces. These are asynchronous 
multiplexers and single-line interfaces used almost exclusively for 
terminal communications. Transfers on all of these interfaces are 
performed one character at a time. None of the interfaces in this 
category has a driver of its own (that is, they are supported by the 
terminal driver), and none can be accessed directly as RSX-11M 
devices. 


Message-oriented communications line interfaces are used primarily to 
link two separate but complementary computer systems. One system must 
serve as the transmitting device and the other as the _ receiving 
device. Devices in this category include the synchronous’ and 
asynchronous single-line interfaces summarized in Table 12-1. 


The message-oriented communication line interfaces are used primarily 
to transfer large blocks of data. 


Whereas the character-oriented interfaces can only be accessed 
indirectly through the terminal driver, the DAl1-B, DL11-E, DMCll, 
DP1l1, DQ11, DU11, and DUP11 allow I/O requests to be queued directly 
for them. These devices have drivers of their own and can be accessed 
by means of the logical device names listed in Table 1-1. These names 
can be used in assigning LUNs with the Assign LUN system directive, at 
task build, or with the REASSIGN MCR command. The following 
subsections briefly discuss the message-oriented interfaces supported 
for RSX-11M. 
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Table 12-1 
Message-Oriented Communication Interfaces 


Rate Duplex Data block Synchronous 
(KBaud) Half/Fulli (words) Character 


Parallel 500 No 
Serial, asynchronous 0.05-9.6 | Programmable 


Serial, synchronous 19.2-1000 No 


Serial, synchronous 2-19.2 Programmable 


Serial, synchronous 2.4-1000 Programmable 
Serial, synchronous 0.05-9.6 Programmable 


Serial, synchronous 0.05-9.6 Programmable 


1. Support is not provided on RSX-11M-PLUS systems. 


2. DL11-E support is provided on RSX-11M-PLUS systems uSing the full-duplex 
terminal driver only. 


12.1.1 DA11-B Parallel Interface 


The DA11-B provides a bit-parallel, direct memory access’ interface 
between two PDP-11 computer systems. Data transfers are performed a 
word at a time and are made directly between the memories of the two 
systems. The maximum transfer rate is 500,000 baud, and is adjustable 
by the user to match the system configuration requirements. Being a 
parallel device, the DA11-B does not utilize sync characters. The 
interface is half-duplex and transfers data in blocks of up to 32K 
words. 


The DAl1-B requires two cooperating computers to effect a data 
transfer. In order to control the physical link between’ the 
computers, the device driver contains its own simple line. protocol. 
This protocol requires one system to issue a receive QIO and the other 
to issue a transmit QIO before any data is actually transferred. 


12.1.2 DL11-E Asynchronous Line Interface 


The DL11-E is an asynchronous, serial-bit, single-line interface. It 
is a block-transfer device used for remote terminal and multicomputer 
communications. Baud rates are selectable between 50 and 9600, and 
full data-set control is supported.l 


1. Software support for data-set control consists of interlocking RTS 
and CTS for data transmission, and the setting of DTR (data terminal 
ready) to enable auto-answer modems to answer incoming calls. DTR is 
set when an IO.INL QIO (initialize) is issued. 
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12.1.3 DMC11 Synchronous Line Interface 


The DMCll provides a direct memory access interface between two PDP-1l 
computer systems uSing the DDCMP line protocol, thus delivering high 
throughput and reliability while simplifying programming. The DMC11 
supports Non-Processor Request (NPR) data transfers of up to 8K words 
at rates of 1,000,000 baud for local operation (over coaxial cable) 
and 19,200 baud for remote operation (using modems). Both full- and 
half-duplex modes are supported. The DMCll also implements’ remote 
load detect, allowing it to reinitialize a halted computer system. 


12.1.4 DP11 Synchronous Line Interface 


The DPll provides a program interrupt interface between a PDP-1l and a 
serial synchronous’) line. This interface facilitates the use of the 
PDP-11 in remote batch processing, remote data collection, and remote 
concentration applications. The modem control feature allows the DP11 
to be used in switched or dedicated configurations. 


On the DPll, baud rates are selectable between 2000 and 19,200. The 
Programmer can select a specific syne character that is used to 
synchronize the transmitting and receiving systems. 


12.1.5 DQ11 Synchronous Line Interface 


The DQ11 provides a direct memory access interface between a PDP-1l 
and a serial synchronous line. The direct memory access 
characteristic of the DQ11 allows the device to operate at speeds 
higher than those of program interrupt devices, and with a lower 
interrupt overhead. Modem control of the DQ11 allows the device to be 
used in switched or dedicated configurations. 


The DQ11 handles data rates from 2400 baud to 1,000,000 baud. The 
limiting rate is determined by the modem and data set interface level 
converters. 


The DQ11 sync character is programmable in the same manner as the DP1l 
and the Dull. The maximum data block length transmitted is 65,536 
characters. 


12.1.6 DU11 Synchronous Line Interface 


The DU11 synchronous line interface is a single-line communications 
device that provides a program-controlled interface between the PDP-11 
and a serial synchronous line. The PDP-1l1 can be interfaced with a 
high-speed line to perform remote batch processing, remote data 
collection, and remote concentration applications. Modem control is a 
Standard feature of the DU1l and allows the device to be used in 
switched or dedicated configurations. The DUll transmits data at a 
maximum rate of 9600 baud; this rate is limited by modem and data set 
interface level converters. 


The DU11 can be programmed to accept any user-defined sync character. 
The use of the sync character is the same for the DU1i and the DPii. 
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12.1.7 DUP11 Synchronous Line Interface 


The DUP11 is identical to the DU11, except that it incorporates 
hardware to perform cyclic redundancy checking. 


12.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for message-oriented communication interfaces. A bit 
setting of 1 indicates that the described characteristic is true for 
the interfaces described in this chapter. 


Bit Setting Meaning 
0 0 Record-oriented device 
i 0 Carriage-control device 
2 0 Terminal device 
3 0 File-structured device 
4 0 Single-directory device 
5 0 Sequential device 
6 0 Mass storage device 
7 0 User-mode diagnostics supported 
8 0 Device supports 22-bit direct addressing 
9 0 Unit software write-locked 
10 0 Input spooled device 
11 0 Output spooled device 
12 0 Pseudo device 
13 i. Device mountable as a communications channel 
14 0 Device mountable as a FILES-11 volume 
LS a Device mountable 


Words 3 and 4 are undefined, and word 5 has a special meaning for the 
DLI1-E, DQ11, DP1l, and the DU11 interfaces. Byte 0 of word 5 
contains the number. of sync characters to be transmitted before a 
synching message (for example, after line turn-around in half-duplex 
operation), and byte 1 is used as a sync counter. 
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12.3 QIO MACRO 
This section summarizes the standard and device-specific functions of 


the QIO macro that are valid for the communication interfaces 
described in this chapter. 


12.3.1 Standard QIO Functions 


Table 12-2 lists the standard functions of the QIO macro that are 
valid for the communication devices. 


Table 12-2 
Standard QOIO Functions for Communication Interfaces 


Format Function 


IO.ATT,... Attach devicel 


TO. DET 5-6 x Detach device 
TORT bye o2s Cancel I/O requests 


IO.RLB,...,<stadd,size> READ logical block (stripping 
sync) 


IO.WLB,...,<Sstadd,size> WRITE logical block (preceded by 
syncs) 


1. Only unmounted channels may be attached. An attempt to attach 
a mounted channel will result in an IE.PRI status being returned 
in the I/O status doubleword. 


stadd 


The starting address of the data buffer (may be on a byte 
boundary). 


size 


The data buffer size in bytes (must be greater than 0). 


12.3.2 Device-Specific QIO Functions 


The specific functions of the QIO macro that are valid for the 
communication line interfaces are shown in Table 12-3. 
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Table 12-3 
Device-Specific QIO Functions for Communication Interfaces 


IO. FDX Set device to full-duplex mode; 
Not applicable to DA11-B 


IO.HDX,...,<Stat,mode> SET device to half-duplex mode; 
Not applicable to DA11-B 


TO. INL <0 Initialize device and set device 
characteristics 


IO.RNS,...,<stadd,size> | READ’ logical block, without 
stripping sync characters 
(transparent mode); Not applicable 
to DQl11; for DA1l1-B and DMClI1, 
treated like IO.RLB 


LO.SYN, sos SSyn> SPECIFY sync character; not 
applicable to DA11-B or DMCl1l 


TOs TRM > é«:< Terminate communication, 
disconnecting from physical channel 


IO.WNS,...,<Sstadd,size> | WRITE logical block without 
preceding sync characters 
(transparent mode); for DA11-B and 
DMC1ll1, treated like IO.WLB 


stadd 


The starting address of the data buffer (may be on a byte 
boundary). 


size 


The data buffer size in bytes (must be greater than 0). 


syn 


The sync character, expressed as an octal value. 


stat 


The station assignment (primary or secondary). 


mode 


The transmission mode (normal or maintenance). 


The device-specific functions listed in Table 12-3 are described in 
greater detail below. 
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12.3.2.1 I0O.FDX - The IO.FDX QIO function is used to set the mode on 
a DLI11-E, DP11, DQ11, DU11, DUP11, or DMCll1 unit to full-duplex. The 
IO.FDX function code can be combined (ORed) with the I0.SYN function 
code, if desired, to set the operational characteristics of the 
physical device unit. 


12.3.2.2 I0O.HDX - The IO.HDX QIO function is used to set the mode on 
a DLI1-E, DP1l1, DQ11, DU11, DUP11, or DMC1ll unit to half-duplex. The 
IO.HDX function code can be combined (ORed together) with the I0.SYN 
function code, if desired, to set the operational characteristics of 
the physical device unit. 


Setting half-duplex on the DMCll also involves setting the _ station 
assignment (primary/secondary) and may include selecting maintenance 
mode (MOP) as opposed to normal mode. The station assignment is 
included in optional QIO parameter pl. A O indicates primary station 
and a nonzero indicates secondary station. The DMCll works’ properly 
if both ends are primary stations or if there is one primary and one 
secondary station. It does not work if both ends are _ secondary 
stations. Optional QIO parameter p2 is used to select the mode. A 0 
selects normal mode and a nonzero selects MOP mode. A DMCl1 in MOP 
mode cannot communicate with a DMCl11 in normal mode. 


12.3.2.3 IO.INL and IO.TRM - These two QIO functions have the same 
function code but different modifier bits. IO.INL is used _ to 
initialize a physical device unit for use aS a communications’ link. 
It turns the device on line, sets device characteristics, and ensures 
that the appropriate data terminal is ready. I10.TRM disconnects’ the 
device. If the device has a dial-up interface, it also hangs up the 
line. - 


12.3.2.4 I0O.RNS - The IO.RNS QIO function is used to read a logical 
block of data, without stripping the sync characters that may precede 
the data. A similar function is IO.RLB, which is nontransparent, in 
that it causes sync characters preceding the data message to be 
stripped. IO.RLB is used at the start of a segmented data request, in 
which the block might have the following layout: 


12 3 4 5 6 7 8 


ZK-007-81 


S 

A syne character. 
H 

A header character. 
CS 


A validity check character. 


L2-7 


MESSAGE-ORIENTED COMMUNICATION DRIVERS 


The programmer must strip sync characters from the beginning of a data 
block in this way. Stripping only at the beginning of a read allows a 
later character which happens to have the same binary value aS a sync 
character to be read without stripping. I0O.RLB is used to read a 
logical block with leading sync characters stripped; I0.RNS is’ used 
to read the block without stripping leading sync characters. Since 
the DA11-B is a parallel device and there are no sync characters, it 
treats the latter as if it were IO.RLB. Generally, IO.RLB should be 
used. 


12.3.2.5 IO.SYN - This QIO function allows the programmer to specify 
the syne character to be recognized when an IO.RLB or IO.WLB function 
is performed. I0O.SYN can be combined (ORed together) with I0O.HDX or 
with IO.FDX to set the characteristics of the physical device unit. 


12.3.2.6 IO.WNS - This QIO function causes a logical block to be 
written with no preceding syne characters. To ensure that the two 
systems involved in a communication are synchronized, two or more sync 
characters are transmitted by one system and received by the other 
before any other message can be sent. I0.WLB is used to write a block 
of data, preceded by sync characters; I0O.WNS is used to perform a 
block transfer without sending sync characters first. Since the 
DA11-B is a parallel device and there are no sync characters, it 
treats the latter as if it were IO.WLB. Generally, IO.WLB should be 
used. 


12.4 STATUS RETURNS 


The error and status conditions listed in Table 12-4 are returned by 
the communication drivers described in this chapter. 


Table 12-4 
Communication Status Returns 


IS.SUC Successful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the I/0 
Status block can be examined to determine the number 
of bytes processed, if the operation involved reading 
or writing. 


IS. PND I/O request pending 
The operation specified in the QIO directive has not 


yet been executed. The I/O status block is filled 
with Os. 


(continued on next page) 


12-8 


MESSAGE-ORIENTED COMMUNICATION DRIVERS 


Table 12-4 (Cont.) 
Communication Status Returns 


Block check error 


When the Cyclic Redundancy Check (CRC) option is 
present on the DQl11, a check character is appended to 
each message transmitted. The receiver of the 
messages recalculates the check character and 
compares it with the one transmitted. This error 
code is returned when the two check characters do not 
match, and represents a transmission error. 


| 

IE.CNR Connection rejected | 
(DMCl11 only.) The DMCll has detected that the device 
on the other end of the line has restarted itself. 
The user can recover by issuing IO.INL (initialize), 
and then reissuing the QIO in question. 

IE.DAO Data overrun 
Due to UNIBUS traffic or a modem problem, the DQl11l 
controller wasS unable to maintain the data rate 
required to prevent data loss (that is, the receipt 
of another byte before processing of a previous byte 
was completed). 

IE.DNR Device not ready 


The physical device unit specified in the QIO 
directive was not ready to perform the desired I/0 
operation. This code is returned to indicate one of 
the following conditions: 


e The physical device unit could not be initialized 
(that is, the circuit could not be completed). 


The transmission of a character was not followed 
by an interrupt within the period of time selected 
as the device time-out period. This time-out 
occurs only when a transmission is in progress and 
the interrupt marking completion of a message does 
not occur. The appropriate response to this 
condition is to attempt to resynchronize the 
device by initializing and accepting the next 
request. A time-out does not occur ona read. If 
the receiving device is not ready, the transfer 
will not be initiated by the transmitting device. 
Once the transfer is initiated, however, it will 
complete either by satisfying the requested byte 
count or by timing out. 


(continued on next page) 


L293 


MESSAGE-ORIENTED COMMUNICATION DRIVERS 


Table 12-4 (Cont.) 
Communication Status Returns 


IE.IFC Illegal function 


A function code was specified in an I/O request that 
is illegal for message-oriented communication 
devices. 


IE.OFL Device off line 


The physical device unit associated with the LUN 
specified in the QIO directive was not on line. When 
the system was booted, a device check indicated that 
this physical device unit was not in the 
configuration. 


IE.SPC Illegal address space 


The buffer specified for a read or write request was 
partially or totally outside the address space of the 
issuing task. Alternatively, a byte count of O was 
specified. — 


TE.VER Nonrecoverable error (DA11-B only) 


The data transfer terminated before all of the data 
has been transmitted. The error code is returned on 
transmit when both systems attempt to transmit at the 
same time. This condition is detected by the device 
protocol. The error code is returned on receive when 
the transmit data count of the transmitting side does 
not equal the data count specified by the _ receive 
QIO. 


IE.ABO Operation Aborted 


The specified I/O operation was canceled by I0.KIL 
while in progress or while still in the I/O queue. 
IE.RSU Sharable Resources in use 
The task attempted to allocate Unibus Mapping 


Registers. All UMRs' were allocated to other tasks 
and were unable to complete the transfer. 


IE.TMO Timeout Error 


The physical device unit associated with the LUN 
specified in the QIO directive timed out. This 
occurs during a data transfer operation when the task 
does not receive an interrupt within a specified 
amount of time. 
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12.5 PROGRAMMING HINTS 


This section contains information on important programming 
considerations relevant to users of the message-oriented communication 
interfaces described in this chapter. 


12.5.1 Transmission Validation 


Because there is no way for the transmitting device to verify that the 
data block has successfully arrived at the receiving device unless the 
receiver responds, the transmitter assumes that any message that is 
clocked out on the line (without line or device outage) has been 
successfully transmitted. As Soon as the receiver is able to satisfy 
a read request, it returns a successful status code (IS.SUC) in the 
I/O status block. Of course, only the task receiving the message can 
determine whether the message has actually been transmitted 
accurately. 


The receiving device should be ready to receive data (with a_e read 
request) at the time the transmission is sent. 


12.5.2 Redundancy Checking 


By the nature of message-oriented communications, only the task that 
receiveS a communication can determine whether the message was 
received successfully. The transmitter simply transfers data, without 
validation of any _ kind. It is therefore the responsibility of the 
communicating tasks which use the device to check the accuracy of the 
transmission. A simple validity check is a checksum-type longitudinal 
redundancy check. A better approach to validating data is the use of 
a cyclic redundancy check (CRC). A CRC can be computed in software or 
with a hardware device, such as the kKG-1l1l communications arithmetic 
option. 


Both DQ11 and DUP11 incorporate hardware to compute a CRC. The DQl11 
CRC hardware requires an extra system unit. 


12.5.3 Half-Duplex and Full-Duplex Considerations 


Because there is a Single I/O request queue, only one QIO request can 
be performed at atime. It is therefore not possible, through QIOs, 
for a device to send and receive data at the Same time. Also, since 
timeouts are not set for receive functions, a receive QIO is 
terminated only by receiving a message from the remote system, or by 
issuing an I0O.KIL QIO for the device. Therefore, if no message is 
transmitted by the remote system, a receive will not terminate, and no 
further I/0 can be performed on that device until the receive is 
killed by issuing an IO.KIL QIO. 


Both half-duplex and full-duplex lines can be used with the DL11-E, 
DMCl1, DP11, DQ11, DU11l, and DUP11. The mode is settable by using 
IO.FDX for full-duplex and IO.HDX for half-duplex. In half-duplex 
mode, the modem signal RTS (Request To Send) is cleared after each 
“transmit message." In full-duplex, this signal is always left on. 
Using full-duplex mode eliminates modem delays in transmission, but 
requires full-duplex hardware and communication links. 
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Only half-duplex mode is available with the DA11-B because of the 
nature of the hardware. 


The DMCll Driver maintains both transmits and receives separately in 
its own internal queues. Thus, it is a full-duplex driver. There is 
no limit on the number of outstanding I/O requests that can be active 
at any given time. The DMCl1l hardware, however, allows a maximum of 
only seven transmits and seven receives to be active at any time. The 
driver gives the first seven transmits (or receives) directly to the 
DMC1l and queues the eighth and subsequent transmits (or receives) 
internally until the DMCll acknowledges a successful I/O request. 
When running on an 11/70, the driver gives only two transmits (or 
receives) to the DMCll because each request requires a UNIBUS mapping 
register. The DMCll driver is assigned five UMRs: one for base 
table(s), two for active transmits, and two for active receives. 


12.5.4 Low-Traffic Syne Character Considerations 


If message traffic on a line is low, each message sent from a 
communications device should be preceded by a sync train. This 
enables the controller to resynchronize if a message is "broken" (that 
is, part or all of it is lost in transmission). Correspondingly, 
every message received by a communications device under low-traffic 
conditions, when messages are not contiguous (back-to-back), should be 
read with an IO.RLB (read, strip sync) function. This requires that 
the first character in the data message itself not have the binary 
value of the sync character. 


12.5.5 Vertical Parity Support 


Vertical parity is not supported by the DA11-B, DL11-E, DPll, DQ1l, or 
DU11. Codes are assumed to be 8-bit only. 


12.5.6 Powerfail with DMCll 


The DMCll currently cannot recover after a power failure because’ the 
RAM in its internal microprocessor is erased when power fails. Any 
I/O requests outstanding at the time of a power failure will return 
IE.ABO. These requests must be reissued after initializing the DMCll 
(IO.INL). 


12.5.7 Importance of IO.INL 


After the type of communication line has been determined, and after 
IO.SYN has specified the syne character, it is extremely important 
that IO.INL be issued before any transfers occur. This ensures’ that 
appropriate parameters are initialized and that the interface is 
properly conditioned. Note that IO.INL provides the only means of 
setting device characteristics, such as sync character. For this 
reason, IO.INL Should always be used immediately prior to the first 
transfer over a newly activated link. 
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Tasks sending messages to the DMCl1 should begin by terminating and 
reinitializing the device (IO.TRM,IO.INL).1 IO.INL must be issued 
after each I0.KIL (which effectively kills the DMC11), after 
power-fail, and upon receipt of any error code. 


12.6 PROGRAMMING EXAMPLE 


The following example illustrates the initialization, setting of 
device parameters, and transmission of a block of data on a 
message-oriented communication device. 


-MCALL ALUNSS,QIOSS 


e e 


ALUNSS #1,#"XP,#0 ; USE LUN1 FOR DP1ll 
QOIOSS #IO.HDX!IO.SYN,<#1,,,,,#226> ; SET DEVICE PARAMETERS 
QIOSS #IO.INL, #1 ; PUT DEVICE ON LINE 
QIOSS #IO.WLB,#1,,,<#TXSTS,#TXAST, #TXBUF,#100>; SEND A BLOCK 


TXAST: CMPB #I1S.SUC&377,@(SP)+ ; WAS DATA CLOCKED OU 
3; SUCCESSFULLY? 
; IF SO, SET UP FOR NEXT 
BEQ 10$ 7 BLOCK 


1. Note that this will cause the error IE.CNR to be returned on any 
I/O outstanding on the other end of the line. 
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PCL11 PARALLEL COMMUNICATIONS LINK DRIVERS 


13.1 INTRODUCTION 


PCL11 Parallel Communications’ Link hardware is supported on 
RSX-11M-PLUS systems by two drivers. One driver supports’ the 
transmitter function and the other driver supports the receiver 
function. The PCL11-B is a hardware interface that functions as a 
time division multiplexed (TDM) interface over which several PDP-11 
computers can transfer data to each other. Each PCL11-B consists of a 
transmitter, receiver, and master section. The transmitter section 
can transfer parallel 16-bit words along the TDM bus to a receiver 
section of a separate PCL11-B on a different PDP-11 computer's UNIBUS. 
One of the PCL11-B units attached to the TDM bus must have its master 
section enabled to effect the data transfer. 


13.1.1 PCL11-B Hardware 


Each PCL11-B transmitter and receiver section has a unique TDM bus 
address (hardware-configured). When a master section is enabled, it 
places a transmitter address on the TDM bus for a period of time, 
called a timeslice. During the timeslice, the addressed transmitter 


can address the desired receiver section and transmit one word; the 
transmitter waits for the receiver to acknowledge the word or an 
indication that the word was not accepted. Tf the word is not 


accepted, it will normally retransmit the word on the next available 
timeslice. Thus, a message up to 32k words long can be transmitted to 
a receiver one word at a time during the time in which other similar 
TDM transactions are multiplexed for other PCL11-B devices. 


13.1.2 PCL11 Transmitter Driver 


The PCL11 transmitter driver provides two basic functions. First, it 
must receive data sent by the attached task and store it in a silo 
buffer in the PCL11 hardware. Then, the driver passes proper receiver 
address and command information to the PCL11 transmitter hardware to 
effect the actual transfer over the TDM bus. 


13.1.3 PCL11 Receiver Driver 


The PCL11 receiver driver also performs two basic functions. First, 
it must remove data from the receiver silo and_ send it to the 
connected task. In addition, the receiver driver must acknowledge a 
transmitter when a data transmission is requested by that transmitter. 
Subsequent requests by other transmitters on the TDM bus are _ ignored 
until all message transactions with the current transmitter are 
completed. 
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13.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for the PCL11 transmitter and receiver drivers. A setting 
of 1 indicates that the described characteristics is true for PCL11l 
transmitter and receiver drivers. 


Bit Setting Meaning 
0 dl Record-oriented device 
4 0 Carriage-control device 
2 0 Terminal device 
3 0 File-structured device 
4 0 Single-directory device 
5 1 Sequential device 
6 0 Mass storage device 
7 0 User-mode diagnostics supported 
8 0 Device supports 22-bit direct addressing 
9 0 Unit software write-locked 
10 0 Input spooled device 
oe 0 Output spooled device 
12 0 Pseudo device 
13 0 Device mountable as a communications channel 
14 0 Device mountable as a FILES-11 volume 
15 0 Device mountable 


Word 3 contains device driver-specific information, as follows: 
Transmitter driver: 


The low byte of word 3 contains the number of transmit retries 
remaining after completing the current data transmit function if 
the current data transmit function attempt is not accepted by the 
addressed receiver. The high byte of word 3 is undefined. 


Receiver driver: 


The low byte of word 3 contains the index of the current state of 
the receiver driver. These states are primarily used for 
diagnostic purposes and are defined as follows: 


Index Value Meaning 
0 No task is connected. 
+2 Task connected but not triggered. 
+4 Task triggered and waiting for I0.RTF or 


IO.ATF function. 
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Index Value Meaning 


+6 Task triggered and timed out while waiting for 
IO.RTF or IO.ATF function. 


~2 IO.ATF function is in progress. 


-4 Task connected, not triggered, and has an 
IO.ATF function in progress. 


~6 An IO.RTF function is in progress. 
The high byte of word 3 is undefined. Word 4 is undefined. Word 5 is 


the default buffer size in bytes. For the PCL11, this value is 64 
bytes. 


13.3 QI0 MACRO -- PCL11 TRANSMITTER DRIVER FUNCTIONS 
13.3.1 Standard QIO Functions 
Table 13-1 lists the standard functions of the QIO macro that are 


valid for the PCL11 transmitter driver. 


Table 13-1 
Standard QIO Functions for PCL11 Transmitters 


QOLOSE LO VATT, 3:6 Attach device 


OLOSC I0.-DET /-s«« Detach device 


OLOSC. TOOK Ip xc.< Cancel I/O request 


13.3.2 Device-Specific QIO Functions 


Table 13-2 lists the device-specific functions of the QIO macro. that 
are valid for the PCL11 transmitter driver. 


Table 13-2 
Device-Specific QIO Functions for PCL11 Transmitters 


QIOSC IO.ATX,...,<stadd,size, 
flagwd,id,retries,retadd> 


Attempt message transmission 


OIOSC IO.STC,...,<stadd,size, 
[state] ,[{mode],,retadd> Set master section characteristics 
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stadd 


The starting address of a data buffer. (Its description and 
function is dependent upon the specific QIO function.) 


size 
The data buffer size in bytes. (Its description and function is 
dependent upon the specific QIO function.) 

flagwd 
The value of the flagword that is to precede the message being 
sent. The flags specify the desired receiver function as defined 
by the user's protocol. 

id 
The identifier of the CPU to which the message is to be sent. 
This identifier is the desired receiver's TDM bus address. It 
appears in the high byte of the first word of the master section 
I/O status block. The identifier number is an octal value 
contained in the high byte of the parameter word. For example, 
receiver number 1 is specified as 400, receiver number 2 is 
specified as 1000, and so forth. 

retries 
The number of retries that will be attempted, following the first 
attempt, that will be performed if the first attempt is 
unsuccessful, or upon detecting transmission errors or master 
down conditions, before returning error status to the calling 
task. 

retadd 
The starting address of a 7-word buffer into which the contents 
of the six transmitter registers and the transmitter 
master/maintenance register are moved prior to returning to. the 
calling task. Information describing the contents of these 
registers can be obtained by referring to the hardware 
documentation supplied with the PCLil option. 

state 


The desired state setting for the transmitter, as follows: 


Parameter 
Specified State 

SS.MAS TDM bus master 

SS.NEU Neutral (default state) 
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mode 


The desired mode setting for allocating transmitter timeslices on 
the TDM bus, as follows: 


Parameter 

Entered Mode 

MS.AUT Auto addressing (default mode) 
MS.ADS Address silo 


13.3.2.1 IO.ATX - This I/O function requests an attempt to transmit a 
message to a specified CPU. The message to be transmitted is 
contained in a data buffer starting at the address specified in the 
stadd parameter. This address must be on a word boundary. The data 
buffer size specified in the size parameter must be an even, positive 
value. The flagword parameter contains user-defined information that 
the receiving task will use in determining whether to accept or reject 
the message. The id parameter is the receiver TDM bus address. The 
task uses this address to direct a message to a specific CPU. Other 
parameters are as previously described. 


13.3.2.2 I0.SEC - This I/O function is used to sense the master 
section status. Upon successful completion of this function, the I/0 
Status block will contain a typical I/O status code (IS.SUC) return in 
the low byte of the first word, and current Transmitter 
Master/Maintenance Register (TMMR) contents in the second word, as 


follows: 


Current TMMR Contents 


NOTE 


The optional isb parameter (see Section 
1.5.1) must be included in this QIO 
request. 


13.3.2.3 I0.STC - This I/O function sets the master section 
operational characteristics. IO0.STC can only be issued by a 
privileged task. Correct use of the function depends upon the current 
(or specified) operating state of the master section and proper use of 
parameters. Each parameter is used as described in the following 
paragraphs. Refer to all parameters in the sequence shown for a 
correct interpretation of parameter usage. 
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State -- The state parameter determines the overall function of this 
master section (and transmitter and receiver sections) in the PCL11 
communications link as it relates to the TDM bus. The neutral. state 
(SS.NEU) places the master section in an inactive state where the unit 
will send and receive messages in a normal manner, but the master 
section cannot control transmitter timeslice allocation on the TDM 
bus. The master state (SS.MAS) designates this unit as TDM bus 
master, enabling control of transmitter unit timeslice allotments on 
the TDM bus; only one master section on the TDM bus can be designated 
TDM bus master. 


Mode -- The TDM bus master can allocate transmitter timeslices in one 
of two ways: auto address mode (MS.AUT) or address’ silo mode 
(MS.ADS). When operating in the auto address mode (MS.AUT), which is 
the default mode for the TDM bus master, equal timeslice allotments 
are given to each transmitter unit; transmitter unit addresses are 
sequentially put on the TDM bus in descending order, one address for 
each timeslice. When operating in the address silo mode, transmitter 
unit addresses are transmitted in a user-specified sequence, allowing 
up to 50% of the timeslices to be allocated to one transmitter unit, 
if desired. 


The actual sequence of transmitter timeslice allocations for the 
address silo mode is set up in the user's task data buffer referenced 
by the stadd parameter. Certain constraints must be observed when 
specifying this information, as follows: 


e Each entry in the buffer is a byte containing a transmitter 
unit address. 


e At least 20 entries, but not more than 50 entries, must be 
specified. If less than 20 entries are specified, the driver 
will repeat the entire sequence, as specified, in order to 
attain the required minimum of 20 addresses. If more than 50 
addresses are specified, no change in timeslice allocation 
will be effected and an IE.VER error status will be returned 
to the task. 


e Identical transmitter addresses in either adjacent bytes or in 
first and last bytes should be avoided. When identical 
addresses appear in adjacent bytes in this manner, the driver 
inserts invalid "pad" transmitter addresses between identical 
addresses, effectively resulting in no-operation timeslices. 


e Transmitter addresses are decimal values ranging from 1 to 32 
(inclusive) which correspond to addresses implemented on the 
actual transmitter unit hardware. 

e The size parameter must correctly specify the number of 


address bytes contained in the buffer referenced by the stadd 
parameter. 


13.4 PCL11° TRANSMITTER DRIVER STATUS RETURNS 


Table 13-3 lists PCL11 transmitter driver return status codes’ and 
probable reasons. 
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Table 13-3 
PCL11 Transmitter Driver Status Returns 


Reason 


IS.SUC Successful completion 


The QIO function was successfully completed. Le 
an I0.ATX function was completed, the second 
status word contains the number of bytes 
transferred; the message was not truncated. If 
an I0.SEC function was completed, the second 
Status word contains the current contents of the 
| master section's TMMR. 
IS.TNC | Successful transfer but message truncated 
The IO.ATX function was completed, but the message 
was truncated by the receiver (the receiver buffer 
is too small). The transmitter unit cannot 
determine how many words were actually received by 
the receiver unit; the second word of the I/O 
status block contains the length of the requested 
transfer, rather than the actual count of words 
successfully received in the receiver's buffer. 
IE.BAD Bad parameter specification 
A bad parameter specification was included in the 
IO.ATX function, or an invalid state parameter or 
TDM bus timeslice allocation addressing mode was 
specified in the I0.STC function. 


function, issued to a TDM bus master operating in 
the address silo mode, refers to a data buffer 
containing an illegal series of transmitter 
addresses. An illegal series of addresses occurs 
when the number of entries specified for the 
timeslice allocation, plus the required number of 
pad addresses, either exceeds 50 or is less than 
O's 


IE.DNR 


Device not ready 


This error status return occurs in response to an 
IO.ATX function when one of the following occurs: 


e Power failure in this CPU. 


e Device time-out (no response from the addressed 
receiver). 


This error status is also returned when an I0.STC 

@ Receiver was too slow in accepting or rejecting 
the transfer request. 

e The master section is inoperative. ThiS error 

status is returned only after the number of 

retries specified in the IO.ATX function have 


been attempted without success. 


(continued on next page) 
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Table 13-3 (Cont.) 
PCL11 Transmitter Driver Status Returns 


IE.VER Unrecoverable error 


The I0.STC function state setting could not be 
achieved because the task is not privileged or 
another device is TDM bus master. 


IE.SPC Illegal user buffer 


The buffer address specified in the IO.ATF 
function is outside of the issuing task's address 
space. 


IE.REJ Transfer rejected 
The data transfer request specified in the I0O.ATX 
function was rejected by the addressed 
receiver--based on the source CPU identifier of 
the task issuing the request--and flagword. 


IE.FLG Event flag already specified 


An event flag was previously specified in an 
I0.STC function. 


IE.BBE Transmission error 
This error status is returned only after the 
number of retries specified in the IO.ATX function 
have been attempted without a successful 
transmission. (Cycle redundancy check errors or 
parity errors have been detected on each attempt.) 

IE.ABO Request terminated 
This status is returned when a= pending 1/0 
function has been aborted in response to an IO.KIL 
function being issued by the task. 

IE. IFC Illegal function 


A function code was specified in an I/O request 
that is illegal for PCL11 transmitters. 


13.5 QIO MACRO -- PCL11 RECEIVER DRIVER FUNCTIONS 
13.5.1 Standard QIO Functions 


Table 13-4 lists the standard function of the QIO macro that is valid 
for the PCL11 receiver driver. 
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Table 13-4 
Standard QIO Functions for PCL11 Receivers 


| Format | Function | 


QOLEOSC TO.KI by ass Cancel I/O request 


13.5.2 Device-Specific QIO Functions 


Table 13-5 lists the device-specific functions of the QIO macro that 
are valid for the PCL11 receiver driver. 


Table 13-5 
Device-Specific QIO Functions for PCL11 Receivers 


IO.CRX,...,<tef,bufadd> CONNECT for reception 
TOMRTE 424% Reject transfer 


IO.ATF,...,<Stadd,size, 
retadd> Accept transfer 


TLOVDRXK js Disconnect from reception 


tef 
The number of a "trigger" event flag that will be set whenever a 
flagword is received over the TDM bus. 

bufadd 
The address of a 2-word buffer containing the transmitter id, 
trigger status, and the flagword. 

stadd 
The address of a data buffer to receive the message. This 
address must occur on a word boundary (even address). 

size 
The data buffer size in bytes. The size specified must be an 
even, positive value. 

retadd 


The address of a 6-word buffer into which the contents cof the six 
PCL11 receiver hardware registers will be returned upon 
successful completion of the function. Information describing 
the contents of these registers can be obtained by referring to 


the hardware documentation supplied with the PCL11 option. 
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13.5.2.1 I0.CRX - This I/O function connects the issuing task to’ the 
receiver, if the receiver is not currently connected to another task. 
When connected, this task is the only task capable of receiving 
messages by means of the receiver on this CPU. The trigger event flag 
(a local, common, or group-global event flag) informs the task when a 
message is pending. It is set when a flagword is received over the 
TDM bus. When this happens, a significant event is declared and _ the 
connected task is considered "triggered." The flagword is the first 
word transmitted by a transmitter when attempting to send a message to 
the receiver unit. 


The bufadd parameter must be included in this I/O function to’ specify 
the address of a 2-word block, as follows: 


sts 
The current trigger status. 

id 
The identification code of the transmitter attempting to send the 
message, 

flagwd 


The flagword transmitted to the connected receiver. 


Based on the information contained in the flagword and the 
identification code of the transmitter unit, the task can accept or 
reject the transfer. (Two I/O functions are provided for this 
purpose; see Sections 13.5.2.2 and 13.5.2.3.) The receiver must 
respond to the transmitter's request within approximately 1.5 seconds; 
otherwise, an IE.DNR error status is returned to the task attempting 
the transmission. 


13.5.2.2 I0O.RTF - This function informs the transmitter device that 
the message is being rejected by the receiver. Any attempt to issue 
this I/O function when the trigger event flag is not set will be 
ignored, and an IE.NTR error status will be returned to the task. 


13.5.2.3 IO.ATF - This function informs the transmitter device that 
the message is being accepted. Parameters specify both the data 
buffer into which the received data will be transferred, and _ the 
6-word buffer that will receive the contents of the receiver section 
hardware registers upon successfully completing the function. 


Unlike the IO.RTF function, the IO.ATF function can be issued before 
the task is triggered. When this is done, the IO.ATF function is 
queued for reception of any flagword. When the flagword is received, 
the receiver driver immediately executes the IO.ATF function; the 
connected task is not triggered and the flagword is not made available 
to the task. This approach is useful when it is not necessary to 
examine flagwords or to accept messages based on the source. 
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13.5.2.4 IO.DRX - This function is issued by a task to disconnect the 
receiver for use by other tasks. 


13.6 PCL11 RECEIVER DRIVER STATUS RETURNS 


Table 13-6 lists PCL11 receiver driver return status codes and 
probable reasons. 


Table 13-6 
PCL11 Receiver Driver Status Returns 


Reason 


Successful completion 


The I/O function or triggering of the task was 
successfully completed. When this status is 
returned upon completion of the IO.ATF function, 
the high-order byte of the first word in the I/0 
status block contains the identification code of 
the transmitter device that sent the flagword. 
The second word of the I/O status block contains 
the number of bytes transferred over the TDM bus. 
When this status is returned aS a result of an 
IO.CRX function, and the task being triggered, the 
I/O status block contains information that enables 
the task to accept or reject the message (see 
Section 13.5.2.1). 


IS.TNC Successful transfer but message truncated 
terminated because the receiver task message 
buffer specified in the IO.ATF function is_ too 
small to contain the message being received. The 
second word of the I/O status word contains’ the 
number of bytes successfully transferred. 

TE.BAD Bad parameter specification 
A bad parameter specification was included in the 
requested function. 

IE.DNR Device not ready 


This error status return occurs in response to an 
IO.RTF or IO.ATF function when one of the 
following occurs: 


e Power failure in this CPU. 


e Device time-out (no response from addressed 
receiver). 


e Receiver was to w in accepting or rejecting 


This I/O status is returned when the message is 
the 


sl 
es 


(tO 


re) 
transfer requ : 


The master section is inoperative. 


(continued on next page} 
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Table 13-6 (Cont.) 
PCL11 Receiver Driver Status Returns 


Illegal user buffer 


The buffer address specified in the IO.ATF 
function is outside of the issuing task's address 
space. 


Task not connected for reception 


The requested function cannot be executed because 
the task is not connected to the receiver. 


Data overrun 


This I/O status code is returned when the task is 
triggered, but the previous transfer request has 
neither been accepted nor rejected. When the task 
issues an IO.RTF or IO.ATF function, it will apply 
to the new (most recent) flagword; the previous 
request is ignored. 


Device already connected for reception 

This I/O status code is returned in response to 
the IO.CRX function when the receiver is already 
connected to this task or any other task. No 
operation is performed. 

Task not triggered 

This I/O status code is returned when ae task 
attempts to issue an IO.RTF function prior to the 
task being triggered. 

Transmission error 

This error status is returned when an  I0.ATF 
function is in progress and a cycle redundancy 
check error or parity error has been detected. 
Request terminated 

This status is returned when a= pending £/0 


function has been aborted in response to an IO.KIL 
function being issued by the task. 


The requested function cannot be executed because 
of a hardware failure. 


l Fatal hardware error 
Tllegal function 


A function code was specified in an I/O request 


| | that is illegal for PCL11 transmitters. | 
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ANALOG-TO-DIGITAL CONVERTER DRIVERS 


14.1 INTRODUCTION 


The AFC11 and ADO1-D analog-to-digital (A/D) converters are used _ to 
acquire industrial and laboratory analog data. (AFC1l1 and ADO1-D 
driver support is not provided on RSX-11M-PLUS systems.) Although each 
has its own driver, programming for both is quite similar and both are 
multichannel, programmable gain devices. The ADO1-D should not be 
confused with the ADUO], a UDC module, which is described in Chapter 
15. Table 14-1 compares the AFCl1 and the ADO1-D briefly, and 
subsequent sections describe these devices in greater detail. 


Table 14-1 
Standard Analog-to-Digital Converters 


Maximum Sampling Rate (Points 200 (20 per single)| Approximately 
per Second) channel 10,000 


Number of Bits 13 or 14 10 or 1l 


Maximum Number of Analog Channels |1024 64 
That Can Be Multiplexed 


14.1.1 AFC11 Analog-to-Digital Converter 


The AFCll is a differential analog input subsystem for industrial 
data-acquisition and control systems. It multiplexes signals, selects 
gain, and performs a 13- or 14-bit analog-to-digital conversion under 
program control. With the use of appropriate signal-conditioning 
modules, the system can intermix and accept low-level, high-level, and 
current inputs, with a high degree of noise immunity. 


14.1.2 ADO1-D Analog-to-Digital Converter 


The ADO1-D is an extremely fast analog data-acquisition system. Le 

multiplexes signals, selects gain, and performs a 10- or 11-bit 

analog-to-digital conversion under program control. The ADO1-D is 
ca 


normally unipolar, but an opticnal ates bipolar 


operation. 


cid 
we 
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14.2 GET LUN INFORMATION MACRO 

If a GET LUN INFORMATION system directive is issued for a _ LUN 
associated with an analog-to-digital converter, word 2 (the first 
characteristics word) contains all 0s, words 3 and 4 are undefined, 


and word 5 is not significant, since there is no concept of a default 
buffer size for analog-to-digital converters. 


14.3 QIO MACRO 


This section summarizes standard and device-specific QIO functions for 
analog-to-digital converter drivers. 


14.3.1 Standard QIO Function 
The standard function that is valid for analog-to-digital converters 


is shown in Table 14-2. 


Table 14-2 
Standard QIO Function for the A/D Converters 


ee ee 
OTOSC 10. KIL oss Cancel I/O requests 


Since all requests are processed within a small amount of time, no 
in-progress request is ever canceled. This function simply cancels 
all queued requests. 


14.3.2 Device-Specific QIO Function 
The device-specific function of the QIO macro that is valid for 


analog-to-digital converters is shown in Table 14-3. 


Table 14-3 
Device-Specific QIO Function for the A/D Converters 


| QIO$C IO.RBC,...,<stadd,size,stenta> | INITIATE multiple A/D 


conversions 
stadd 


The starting address of the data buffer (must be on a word 
boundary). 
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size 
The control buffer size in bytes (must be even and greater’ than 
0); the data buffer is the same size. 
stcnta 
The starting address of the control buffer (must be on a word 
boundary); each control buffer word must be constructed as shown 
in Table 14-4, 
Table 14-4 
A/D Conversion Control Word 
Bits Meaning AFCl1l ADO1-D 
0-11 Channel number Range: 0-1023 Range: 0-63 
12-15 Gain value for this Gain: Gain: 
sample, expressed as 
a bit pattern as 
follows: 
15 14 13 2 
0 0 0 0 1 1 
0 0 0 1 2 2 | 
0 0 ai 0 illegal 4 
0 0 dl 1 illegal 8 
0 al 0 0 10 illegal 
0 1 0 al 20 ; illegal 
0 1 1 0 illegal illegal 
0 J. 1 il illegal illegal 
hi 0 0 0 50 illegal 
1 0 0 1 100 illegal 
1 0 1 0 illegal illegal 
1 0 1 i i illegal 
1 al 0 0 illegal 
1 ul 0 1 illegal 
a 1 1 0 illegal 
Z 1 pl illegal illegal 


14.4 FORTRAN INTERFACE 


A collection of FORTRAN-callable subroutines provide FORTRAN programs 
access to the AFCll and the ADO1-D. These are described in this 
section. All are reentrant and may be placed ina resident library. 


14.4.1 Synchronous and Asynchronous Process Control I/0 


The ISA standard provides for synchronous and asynchronous’ I/0. 
Synchronous I/0 is indicated by appending a "W" to the name of the 
subroutine (for example, AISQ/AISQW). The synchronous call suspends 
task execution until the I/O operation is complete. If the 
asynchronous form is used, execution continues and the calling program 
must periodically test the status word for completion. 
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14.4.2 The isb Status Array 


The isb (I/O status block) parameter is a 2-word integer array that 
contains the status of the FORTRAN call, in accordance with ISA 
convention. This array serves two purposes: 


1. It is the 2-word I/O status block to which the driver returns 
a status code on completion of an I/O operation. 


2. The first word of isb receives a status code from the FORTRAN 
interface in ISA-compatible format, with the exception of the 
I/O pending condition, which is indicated by a status of 0. 
The ISA standard code for this condition is +2. 


The meaning of the contents of isb varies, depending on the FORTRAN 
call that has been executed; but Table 14-5 lists certain general 


principles that apply. The section describing each subroutine 
provides further details. 


Table 14-5 
Contents of First Word of isb 


isb(1) 


Operation pending; I/0 in progress 


isb(1) Successful completion 


i) 
W 


Interface subroutine unable to 
generate QIO directive, or number of 
samples is 0 


isb(1) 


3 < isb(1) < 300 QIO directive rejected and actual 


error code = -(isb(l) - 3) 


isb(1) > 300 Driver rejected request and actual 


error code = -(isb(1) - 300) 


Unless otherwise specified, the value of isb(2) is the value returned 
by the driver to the second word of the I/O status block. 


FORTRAN interface subroutines depend on asynchronous system traps to 
set their status. Thus, if the trap mechanism is disabled, proper 
status cannot be set. 


14.4.3 FORTRAN Subroutine Summary 


Table 14-6 lists the FORTRAN interface subroutines supported for the 
AFC11l and ADO1-D under RSX-11M. 
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Table 14-6 
FORTRAN Interface Subroutines for the AFCll and ADO1-D 


Subroutine Function 


AIRD/AIRDW Perform input of analog data in random 
Ss quence 


AISQ/AISOQW Read a series of sequential analog 
input channels 


ASADLN Assign a LUN to the ADO1-D 


ASAFLN Assign a LUN to the AFC11 | 


The following subsections briefly describe the function and format of 
each FORTRAN subroutine call. Note the use of ASADLN and ASAFLN to 
assign a default logical unit number. 


14.4.4 AIRD/AIRDW: Performing Input of Analog Data in Random Sequence 


The ISA standard AIRD/AIRDW FORTRAN subroutines input analog data in 
random sequence. These calls are issued as follows: 


AIRD 
CALL (inm,icont,idata,[isb], [lun] ) 
AIRDW 
inm 
The number of analog input channels. 
icont 


An integer array containing terminal connection data-channel 
number (right-justified in bits 0-11) and gain (bits 12-15), as 
shown in Table 14-4, 


idata 
An integer array to receive the converted values. 
isb 
A 2-word integer array to which the subroutine status is 


returned. 


lun 


The logical unit number. 
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The isb array has the standard meaning defined in Section 14.4.2. If 
inm = 0, then isb(1) = 3. The contents of idata are undefined if an 
error occurs. 


14.4.5 AISQ/AISQW: Reading Sequential Analog Input Channels 


The ISA standard AISQ/AISQW FORTRAN subroutines read a series of 
sequential analog input channels. These calls are issued as follows: 


AISQ 
CALL (inm,icont,idata,[isb],[lun] ) 
AISQW 
inm 
The number of analog input channels. 
icont 
An integer array containing terminal connection data-channel 
number (right-justified in bits 0-11) and gain (bits 12-15), as 
shown in Table 14-4. 
idata 
An integer array to receive the converted values. 
isb 
A 2-word integer array to which the subroutine status is 
returned. 
lun 


The logical unit number. 


For sequential analog input, channel number is computed in steps of 
one, beginning with the vaiue specified in the first element of icont. 
The channel number field is ignored in all other elements of the 
array. 


The gain used for each conversion is taken from the respective element 
in icont. Thus, even though the channel number is ignored in all but 
the first element of icont, the gain must be specified for each 
conversion to be performed. 


The isb array has the standard meaning defined in Section 14.4.2. If 


inm = 0, then isb(1) = 3. The contents of idata are undefined if an 
error occurs. 


14-6 


ANALOG-TO-DIGITAL CONVERTER DRIVERS 


14.4.6 ASADLN: Assigning a LUN to the ADO1-D 


The ASADLN FORTRAN subroutine assigns the specified LUN to the ADO1-D 
and defines it as the default logical unit number to be used whenever 
a LUN specification is omitted from an AIRD(W)/AISQ(W) subroutine 
call. It is issued as follows: 


CALL ASADLN (lun, [isw],[fiun]) 


lun 
The logical unit number to be assigned to the ADO1-D and defined 
as the default unit. 

isw 
An integer variable to which the result of the ASSIGN LUN system 
directive is returned. 

iun 


The unit number to be assigned. If unspecified, a value of 0 is 
assumed. 


Only the LUN specified in the last call to ASADLN or ASAFLN is defined 
as the default unit. 


14.4.7 ASAFLN: Assigning a LUN to the AFC11 


The ASAFLN FORTRAN subroutine assigns the specified LUN to the AFC1l 
and defines it as the default logical unit number to be used whenever 
a LUN specification is omitted from an AIRD(W)/AISQ(W) subroutine 
call. It is issued as follows: 


CALL ASAFLN (lun, [isw],[iun] ) 


lun 
The logical unit number to be assigned to AFCl1 and defined as 
the default unit. 

isw 
An integer variable to which the status from the ASSIGN LUN 
system directive is returned. 

iun 


The unit number to be assigned. If unspecified, a value of 0 is 
assumed. 


Only the LUN specified in the last call to ASAFLN or ASADLN is defined 


as the default unit. 
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14.5 STATUS RETURNS 


The error and status conditions listed in Table 14-7 are returned by 
the analog-to-digital converter drivers described in this chapter. 


Table 14-7 
A/D Converter Status Returns 


IS.SUC Successful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the I/0 
Status block can be examined to determine the number 
of A/D conversions performed. 


IS.PND . I/O request pending 


The operation specified in the QIO directive has not 
yet been executed. The I/O status block is filled 
with Os. 


IE.ABO Operation aborted 


The specified I/O operation was canceled with I0O.KIL 
while still in the I/O queue. 


TE.BAD Bad parameter 


An illegal specification was supplied for one or more 
of the device-dependent QIO parameters (words 6-11). 
For the analog-to-digital converters, this code 
indicates that a bad channel number or gain code was 
specified in the control buffer. 


LE.BYT Byte-aligned buffer specified 


Byte alignment was specified for a data or control 
buffer, but only word alignment is legal for 
analog-to-digital converters. Alternatively, the 
length of the data and control buffer is not an even 
number of bytes. 


The physical device unit specified in the QIO 
directive was not ready to perform the desired I/0 
operation. For the AFCl1, this code is returned if 
an interrupt time-out occurred or the power failed. 
In the case of the ADO1-D, which is not operated in 
interrupt mode, this code indicates a software 
time-out occurred (that is, a conversion did not 
complete within 30 microseconds). 


IE.DNR Device not ready 


(continued on next page) 
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Table 14-7 (Cont.) 
A/D Converter Status Returns 


IE.IFC Tllegal function 


A function code was specified in an I/O request that 
is illegal for analog-to-digital converters. 


The data or control buffer specified for a conversion 
request was partially or totally outside the address 


| | 
IE.OFL | Device off line 
The physical device unit associated with the LUN 
specified in the QIO directive was not on line. When 
the system was booted, a device check indicated that 
this physical device unit was not in the 
| | configuration. 
IE.SPC Illegal address space 


space of the issuing task. Alternately, a byte count 
of 0 was specified. 


FORTRAN interface values for these subroutineS are presented in 
Section 14.5.1. 


14.5.1 FORTRAN Interface Values 


The values listed in Table 14-8 are returned in FORTRAN’ subroutine 
calls. 


Table 14-8 
FORTRAN Interface Values 


Status Return FORTRAN Value 


IS.SUC 
IS.PND 
IE.ABO 
IE.ADP 
IE.BAD 
LE.BYT 
IE.DAO 
IE.DNR 
TEZIEF 
IBSIFC 
IE. ILU 
IE.NOD 
IE.ONP 
IE.PRI 
IE.RSU 
IE.SDP 
ITE.SPC 
IE.ULN 
IE.UPN 
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14.6 FUNCTIONAL CAPABILITIES 


The AFC1l and ADO1-D operate only in multisample mode, because’ the 
user can simulate single-sample mode by simply specifying one sample. 
Multisample mode permits many channels to be sampled at approximately 
the same time without requiring the user to queue multiple I/0 
requests. 


The maximum number of channels in the configuration is specified at 
system-generation time. This value is stored in the respective AFC1l 
and ADO1-D unit control blocks. 


14.6.1 Control and Data Buffers 


The user must define two buffers of equal size: the control buffer 
and the data buffer. The former contains the control words needed to 
perform one A/D conversion per channel specified. Each control word 
indicates the channel to be sampled and the gain to be applied (see 
Table 14-4). 


The data buffer receives the results of the conversions. Each result 
is placed in the data buffer location that corresponds to the control 
word that specified it. 


14.7 PROGRAMMING HINTS 


This section contains information on important programming 
considerations relevant to users of the analog-to-digital converter 
drivers described in this chapter. 


14.7.1 Use of A/D Gain Ranges 


Note that the A/D gain ranges overlap. The key to successful use of 
the A/D converters is to change to a higher gain whenever a full-scale 
reading is imminent, and to change to a lower gain whenever the last 
A/D value recorded was less than half of full scale. This method 
maintains maximum resolution while avoiding saturation. 


14.7.2 Identical Channel Numbers on the AFCI11 


When requesting sampling of more than one channel, the user should not 
specify multiple sampling of a single channel without 10 or more 
intervening samples on other channels. This ensures 50 milliseconds 
between samples on a single channel. If sampling occurs more often 
than this on a single channel, partial results are returned (see 
Section 14.7.3). 
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14.7.3 AFC11l Sampling Rate 


Although the AFC11 can sample a maximum of 200 points per second, a 
Single channel can only be sampled at 20 points per second. Because 
the channel capacitor needs 50 milliseconds to recharge after each 
conversion, more frequent sampling may result in partial readings. If 
this occurs, the user will receive no indication that information is 
being lost. To ensure that information is not lost on any one 
channel, the user should sample approximately 10 other channels before 
returning to the first one. 


14.7.4 Restricting the Number of ADO1-D Conversions 


The ADO1-D is an extremely fast device, providing a 25-microsecond 
conversion rate, and is driven programmably to minimize system 
overhead. However, an excesSive number of conversions in aé_e single 
request essentially locks out the rest of the system, because the 
driver does not return control to the system until it has finished all 
the specified conversions. No other task can run, although interrupts 
can still occur and are processed. 
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15.1 INTRODUCTION 


The UDCl1 is a digital input/output system for industrial and process 
control applications. It interrogates and/or drives up to 252 
directly addressable digital sense and/or control modules. The UDC11 
operates under program control as a high-level digital multiplexer, 
interrogating digital inputs and driving digital outputs. (UDC11 
driver support is not provided on RSX-11M-PLUS systems.) 


The UDC driver will support either the UDCl1 or ICS11 subsystem. The 
ICS11 (Industrial Control Subsystem) operates as an input/output 
device that is functionally similar to the UDC1l1l. A maximum of 16 I/0 
modules can be placed in one ICS11 subsystem; up to 12 ICSl1is can be 
interfaced to one computer system. The ICS11 subsystem is also 
supported by the ICS/ICR-11 driver described in Chapter 18. The 
reader should consult that chapter for a comparison of driver 
features. 


While performing analog-to-digital conversions, the UDCll driver can 
handle other functions, such aS contact or timer interrupts or 
latching output. These functions are performed immediately, without 
requiring any in-progress analog-to-digital conversions to first be 
completed. 


Unlike other RSX-11M I/O device drivers, the UDC1l1 driver is neither a 
multicontroller nor a multiunit driver. 


15.1.1 Creating the UDC11 Driver 


Each installation must assemble the driver source module with a prefix 
file that defines the particular hardware configuration. The prefix 
file is created during system generation according to the user's 
response to queStions relating to the UDC1l1. This file is named 
RSXMC.MAC and includes symbolic definitions of the UDC11 
configuration. These definitions encode the relative module number — 
and the number of modules for each generic type specified in the 
system generation dialog. The encoding has the following format: 


8 


8 
number of modules starting module number 
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One or more of the following symbols is generated: 


Symbol Module Type 

USSADM Analog input 

USSAOM Analog output 

USSCIM Contact interrupt 

USSCSM Contact sense input 

USSLTM Latching digital output 
USSSSM Single-shot digital output 
USSTIM Timer (I/O counter) 


Note that all modules of a given type must be installed together in 
sequential slots. 


15.1.2 Accessing UDC11 Modules 
RSX-11M provides two methods of accessing the UDC11: 
1. A QIO macro call issued to the driver 


2. Restricted direct access by any task to I/O page registers 
dedicated to the UDC11 


The first method, access through the driver, is required to service 
interrupting modules and to set and_ record the state of latching 
digital output modules. 
The second method, direct access, is a high-speed, low-overhead way to 
service noninterrupting modules. The following functions may be 
performed in this manner: 

e Analog output 

e Contact sense input 

e Single-shot digital output 


e Read a contact interrupt module 


e Read a timer module 


15.1.2.1 Driver Services - The driver services the following types of 
modules: 


e Contact interrupt 

e Timer (I/O counter) 

e Analog input 

e Latching digital output 
Contact and timer interrupts need not be serviced by a single task. 
One task may be connected to contact interrupts, and another to timer 
interrupts. A nonprivileged task can connect to either or both of 
these classes by providing a circular buffer to receive interrupt 


information and an event flag to allow triggering of the task whenever 
a buffer entry is made. 
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15.1.2.2 Direct Access - A global common block within the I/0 page 
provides restricted direct access to the UDC11l device registers. Ina 
mapped system, the length of the block is set to prevent access to 
other device registers. In an unmapped system, the use of the common 
block is optional, unless ISA FORTRAN calls are _ used. The ISA 
routines refer symbolically to the UCD11 registers, and thus require 
the use of global common. Section 15.4 explains direct access more 
fully. 


15.2 GET LUN INFORMATION MACRO 

If a GET LUN INFORMATION system directive is issued for a_ LUN 
associated with the UDCl1, word 2 (the first characteristics word) 
contains all zeros, words 3 and 4 are undefined, and word 5 is not 


Significant, since there is no concept of a default buffer size for 
universal digital controllers. 


15.3 QIO MACRO 
This section summarizes standard and device-specific QIO functions for 


the UDC1l1l driver. In issuing them, note the numbering conventions 
described in 15.7.2. 


15.3.1 Standard QIO Function 


The standard function that is valid for the UDCI11 is shown in Table 
15-1. 


Table 15-1 
Standard QIO Function for the UPC11 


ee ee ee 
QIOSC IO.KIL,... Cancel I/O requests 


IO.KIL cancels all queued requests and disconnects all interrupt 
connections, but does not stop any I/O that is currently in progress. 


15.3.2 Device-Specific QIO Functions 


Table 15-2 summarizes device-specific QIO functions that are supported 
for the UDC12. 
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Table 15-2 
Device-Specific QIO Functions for the UDC11 


QTOSC I0.CCI,...,<stadd,sizb,tevf> CONNECT a buffer to contact 
interrupts | 


| OIOSC IO.CTI,...,<stadd,sizb,tevf,arv> | CONNECT a buffer to timer 
interrupts 


LO.sDCT gs 68 Disconnect a buffer from 
contact interrupts 


LOCDT LI pisces Disconnect a buffer from timer 
interrupts 


LO. TT iy ssa <mn; LC INITIALIZE a timer 


IO.MLO,...,<opn,pp,dp> OPEN or close latching digital 
output points 


IO.RBC,...,<stadd,size,stcnta> INITIATE multiple A/D 
conversions 


stadd 
The starting address of the data buffer (must be on a_ word 
boundary). 

sizb 
The data buffer size in bytes (must be even and large enough to 


include a 2-word buffer header plus one data entry; the buffer 
may cross a 4K boundary). 


tevf 
The trigger event flag number. 
arv 
The starting address of the table of initial/reset values (must 
be on a word boundary). 
mn 
The module number. 
1c 
The initial count. 
opn 


The first latching digital output point number, which must be on 
a module boundary (evenly divisible by 16). 


15-4 


UNIVERSAL DIGITAL CONTROLLER DRIVER 


Pp 
The 16-bit mask. 
dp 
The data pattern. - 
size 
The control buffer size in bytes (must be even and greater than 
0); the data buffer is the same size. 
stcnta 


The starting address of the control buffer (must be on aé_e word 
boundary); each control buffer word must be constructed as shown 
in Table 15-3. 


The following sections describe the functions listed in Table 15-2. 


Table 15-3 
A/D Conversion Control Word 


Range: 0-4095 


Channel number 


Gain value for this Gain: 
sample, expressed as 
a bit pattern as 


follows: 


1 
2 
Illegal 
Illegal 
10 
20 
Illegal 
Tllegal 
50 
100 
Illegal 
Illegal 
200 
1000 
Tllegal 
Illegal 


RPHRPHHEEHHOODDOOOOO 
— 
PRP HOOOORHRFHOOOSO |[A 
a 
PRHOOHHOOHHPOOHHOO |w 
FOF DOrFPORPOKFOrRPOHOHO 
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15.3.2.1 Contact Interrupt Digital Input (W733 Modules) - Digital 
input and change of state information from contact interrupt modules 
is reported in a requester-provided circular buffer. The buffer 
consists of a 2-word header, followed by a data area in the following 
format: 


user index 


Whenever a change of state occurs in one or more contact points, an 
interrupt is generated. The UDC1l1 driver gains control, determines 
whether the change of state is of interest (that is, a contact closure 
and point closing . (PCL) is set on the module), and then optionally 
makes an entry in the data area of the buffer, updates the index 
words, and sets the trigger event flag of the connected task. 


Each entry consists of five words in the following format: 


Word Contents 
0 Entry existence indicator 
1 Change-of-state (COS) indicator 
2 Module data (current point values) 
3 Module number (interrupting module) 
4 Generic code (interrupting module) 


The driver enters data in the location currently indicated by the 
driver index. This pointer can be considered as a FORTRAN index into 
the buffer; that is, the first location of the buffer is associated 
with the index 1. The beginning of the data area is the location of 
the first entry (index 3). Entries are made in a circular fashion, 
Starting at the beginning of the data area, filling in order of 
increasing memory address to the end of the data area, and _ then 
wrapping around from the end to the beginning of the data area. 


It is expected that the connected task will maintain its own pointer 
(the user index) to the location in the buffer where it is next to 
retrieve contact interrupt data. When a task is triggered by the 
driver, it should process data in the buffer starting at the location 
indicated by its pointer and continuing in a circular fashion until 
the two pointers are equal or a zero entry existence indicator is 
encountered. Equality of pointers means that the connected task has 
retrieved ail the contact interrupt information that the driver has 
entered into the buffer. 


The entry existence indicator is set to nonzero when a buffer entry is 
made. When a requester has removed or processed an entry, he must 
clear the existence indicator in order to free the buffer entry 
position. 
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If data input occurs in a burst sufficient to overrun the buffer, data 
is discarded and a count of data overruns is incremented. The nonzero 
entry existence indicator also serves aS an overrun indicator. A 
positive value (+1) indicates no overruns between entries; a negative 
value is the two's complement of the number of times data have been 
discarded between entries. 


The module number indicates a module on which a change of state in the 
direction of interest has been recognized for one or more discrete 
points. The direction of the change may be from 0 to 1 or 1 to O, 
depending on the PCL (point closing) and POP (point opening) module 
jumpers. The change of state (COS) indicator specifies which point or 
points of the module have changed state. 


The bit position of an on-bit in the COS indicator provides’ the 
low-order bits (3-0) of a point number and the module number provides 
the high-order bits (15-4). The module data indicates the logical 
value (polarity) of each point in the module at the time of the 
interrupt. 


Contact interrupt data can be reported to only one task. The 
functions I0.CCI and I0.DCI in Table 15-2 are provided to enable a 
task to connect and disconnect from contact interrupts. Le. - he 


connection is successful, the second word of the I/O status block 
contains the number of words passed per interrupt in the low-order 
byte and the initial FORTRAN index to the beginning of the data area 
in the high-order byte. 


NOTE 


The size of the data area must be a 
multiple of the entry size. 


15.3.2.2 Timer (W734 I/O Counter Modules) - A timer (1/0 counter) 
module is a clock that is initialized (loaded), counts up or down, and 
then causes an interrupt. The UDC1l1l driver treats such modules in a 
way Similar to that in which it handles contact interrupts. The 
requester provides a circular buffer similar to that for contact 


interrupts. Each entry consists of four words in the following 
format: 
Word , Contents 
0 Entry existence indicator 
1 Module data (current value) 
2 Module number (interrupting module) 
3 Generic code (interrupting module) 
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The IO.CTI function in Table 15-2 enables a task to connect to timer 
interrupts. The table of initial/reset values is used to initially 
load the timers and to reload them on interrupt (overflow). The table 
contains one word for each timer module. The contents of the first 
word are used to load the first module, and so forth. If a timer has 
a nonzero value when it interrupts, it is not reloaded, so that 
self-clocking modules and modules that interrupt on half count’ can 
continue counting from the initial value. 


The IO.DTI function in Table 15-2 disconnects a task from timer 
interrupts, and the IO.ITI function provides the capability of 
initializing a single timer. Requests to initialize a counter are 
valid only if the issuing task has connected a buffer for receiving 
counter interrupts. 


NOTE 


The size of the data area must be a 
multiple of the entry size. 


15.3.2.3 Latching Digital Output (M685, M803, and M805 Modules) - 
Each module has 16 latching digital output points. The I0.MLO 
function in Table 15-2 opens or closes a set of up to 16 points. Bit 
n of the mask and data pattern corresponds to the point opn +n. If a 
bit in the mask is set, the corresponding point is opened or closed, 
depending on whether the corresponding bit in the data pattern is 
clear or set. If a bit in the mask is clear, the corresponding point 
remains unaltered. 


15.3.2.4 Analog-to-Digital Converter (ADU0O1 Module) - Each ADUO1] 
module has eight analog input channels. The IO.RBC function in Table 
15-2 initiates A/D conversions on multiple ADU0O] input channels. 
Restrictions on maximum sampling rates are the same as those defined 
for the AFC11 in Chapter 14. 


The converted analog value is returned as 12 bits, left-justified, in 
a 16-bit word with the low-order 4 bits set to 0. 


15.3.2.5 ICS11 Analog-to-Digital Converter (IAD-IA Module) - Each 
IAD-IA Module has eight analog input channels. The channel capacity 
may be expanded to 120 by the addition of IMX-IA multiplexers. Each 
multiplexer adds 16 input channels to the converter. Restrictions on 
maximum sampling rates are the same as those defined for the AFC11 in 
Chapter 14. The IAD-IA module preempts eight module slots regardless 
of the number of IMX-IA multiplexers installed. 


For addressing purposes, each converter occupies a block of 120 
channels. Thus, A/D converter 0 is addressed by referencing channels 
0 through 119; A/D converter 1 is addressed by referencing channels 
120 through 239, and so forth. When fewer than seven multiplexers are 
installed, not all addresses within the block are valid. 


The converted analog value is returned as 12 bits, left-justified, in 
a 16-bit word with the low-order 4 bits set to 0. 
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15.4 DIRECT ACCESS 


Section 15.1.2 describes UDC1l1 functions that may be performed by 
referencing a module through its physical address in the I/O page. 
Under RSX-11M such access is accomplished by one of the _ following 
methods: 


l. A privileged task or any task running in an unmapped system 
has unrestricted access to the I/O page, and may therefore 
access each module by absolute address. 


2. Using the Task Builder, a task may link to a global common 
area whose physical address limits span a set of locations in 
the I/O page. This method applies to either a mapped or 
unmapped system. 


The latter method allows a task to be transported to any other system 
simply by relinking. Furthermore, in a mapped system the memory 
management hardware will abort all references to device registers 
outside the physical address limits of the common block. 


The operations required to implement each method may be summarized as 
follows: 


1. Unrestricted access to the I/O page 


a. An object module is created that defines the UDC11 
configuration through a list of absolute global addresses 
and addressing limits for each module type. 


b. The object module is included in the system library file. 


c. A task is created containing the appropriate global 
references. Such references are resolved when the task 
builder automatically searches the system library file. 


Steps a and b are executed once, during system generation (see _ the 
RSX-11M System Generation and Management Guide). Step c is performed 
each time a task 1s created that references the UDC12. 


2. Access to the I/O page through a Global Common Block 


a. An object module is created that defines the UDC1I1 
configuration through a list of relocatable global 
addresses and addressing limits for each module type. 


b. The object module is linked, uSing the Task Builder, to 
create an image of the Global Common block on disk. 


c. The SET command is used to define a common block that 
resides on the I/O page. 


d. The INSTALL MCR command is used to make the Global Common 
Block resident in memory. 


e. A task is created containing the appropriate global 
references. Such references are resolved by directing 
the Task Builder to link the task to the common block. 


Steps a through d are executed once, during system generation. Step e 
is performed each time a task is created that references the UDC11 
common block. The following paragraphs describe each step in detail. 
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15.4.1 Defining the UDC11 Configuration 


The source module UDCOM.MAC,! when assembled with the proper prefix 
file, provides global definitions for the following parameters: 


e The starting address of each module type 
e The highest point number within a given module type 
e The highest module number within a given module type 


The last two parameters are absolute quantities that may be used _ to 
prevent a task from referencing a module that is nonexistent or out of 
limits. 


By means of conditional assembly, the list of addresses may be created 
as absolute symbols defining locations in the I/O page, or as symbols 
within a relocatable program section to be used when building and 
linking to the UDC11 Global Common area. 


15.4.1.1 Assembly Procedure for UDCOM.MAC - UDCOM.MAC is assembled 
with the RSX-11M configuration parameters contained in the file 
RSXMC.MAC. 


To create relocatable module addresses, either the parameter USSDCM or 
MSSMGE must be defined. MSSMGE will be included in RSXMC.MAC if 
memory management was specified when the system was generated. Tf 
not, the user should edit the file to include the following 
definition: 


USSDCM=0 
The file may then be assembled using the MCR command: 
>MAC UDCOM,UDLST=[11,10]RSXMC,UDCOM 


This command invokes the MACRO-11 assembler, which processes the input 
files RSXMC.MAC and UDCOM.MAC to create UDCOM.OBJ and UDLST.LST. 


To create absolute module addresses, both USSDCM and MSSMGE must be 
undefined. Edit RSXMC.MAC, if necessary, to remove definitions and 
then invoke the MACRO-11 assembler with the following MCR command: 


>MAC UDCDF,UDLST=[11,10]RSXMC,UDCOM 
In this sequence the files UDCDF.OBJ and UDLST.LST are created from 


the specified source modules. UDCDF.OBJ contains the module addresses 
in absolute form. 


15.4.1.2 Symbols Defined by UDCOM.MAC - This section lists the 
symbolic definitions created by UDCOM.MAC. 


1. This module resides on the RKO5 cartridge of the RSX-11M RK 
distribution kit labeled EXECUTIVE SOURCE. For RP distribution kits, 
it resides on the RP image. The file is located under UIC [11,10]. 
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The following symbols define the absolute or relocatable address of 
the first module of a given type: 


Symbol Module Type 

$.ADM Analog input 

$.AOM Analog output 

$.CIM Contact interrupt 

$.CSM Contact sense input 

$.LTM Latching digital output 
$.SSM Single-shot digital output 
$.TIM Timer (I/O counter) 


The addresses in relocatable form are defined in a program _ section 
named UDCOM having the attributes: 


REL - relocatable 
OVR - overlaid 
' D - data 


GBL —- global scope 


Note that these attributes correspond to those attached to a named 
common block within a FORTRAN program. 


In either the absolute or relocatable case, individual modules are 
referenced by the corresponding symbolic address plus a relative 
module index. 


The following symbols define the highest digital point within a module 
type: 


Symbol Module Type 

PS.CIM Contact interrupt 

PS.CSM Contact sense input 

PS.LTM Latching digital output 
PS.SSM Single-shot digital output 


The highest point number is defined relative to the first point on the 
first module of a specific type. For example, if two contact 
interrupt modules are installed, the symbol PS.CIM will have an octal 
value of 37. 


The following symbols define the highest module number within a given 
module type. 


Symbol Module Type 

MS.ADM Analog input 

MS .AOM Analog output 

MS.CIM Contact interrupt 

MS.CSM Contact sense input 

MS.LTM Latching digital output 
MS.SSM Single-shot digital output 
MS.TIM Timer (I/O counter) 


The highest module number is defined relative to the first module of a 


given type. Thus, based on the previous example, MS.CIM will have a 
value of l. 
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15.4.2 Including UDC1l Symbolic Definitions in the System Object 
Module Library 


As described in Section 15.4, a task having unrestricted access to the 
I/O page may reference a UDC11 module by absolute address. The object 
module UDCDF contains symbolic definitions of absolute module 
addresses and may be included in the System Object Module Library: 


SY: £1, LJ SYSLIS.0OLB 


The Task Builder automatically searches this file to resolve any 
undefined globals remaining after all input files have been processed. 


The following example illustrates the procedure for including the file 
UDCDF.OBJ in the library: 


>SET /UIC=[1,1] 
>LBR SYSLIB/IN=[200, 200] UDCDF 


The SET MCR command is issued to establish the current UIC as [1,1]. 
Next, the RSX11M Librarian is invoked and instructed, through the use 
of the /IN switch, to include the object module UDCDF.OBJ in the file 
SYSLIB.OLB. 


15.4.3 Referencing the UDC11 through a Global Common Block 


The following sections define the procedure for creating a Global 
Common block in the I/O PAGE, making the block resident in memory, and 
creating a task that references UDC11 modules within the block. 
Examples are given for both mapped and unmapped systems. 


15.4.3.1 Creating a Global Common Block - The following sequence 
illustrates the use of the object file UDCOM.OBJ to create a disk 
image of the global common area in a mapped system: 


>SET /UIC=[1,1] 

>TKB 
TKB>UDCOM/MM, LP: , SY: UDCOM/PI/-HD=[ 200, 200]UDCOM 
TKB>/ 

ENTER OPTIONS: 

TKB>PAR=UDCOM:0:1000 

TKB>STACK=0 

TKB>/ 


In the above example, a current UIC of [1,1] is established and the 
Task Builder is initiated. The initial input line to the Task Builder 
specifies the following files: 

e A core image output file to be named UDCOM.TSK 

e A memory map output to the line printer 

e A symbol table file to be named UDCOM.STB 
All files reside on SY: under UIC {f[1,1]. The single input file 


UDCOM.OBJ, containing the UDC1l1l address definitions as relocatable 
values, constitutes the input. 
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The switches specified for the output files convey the following 
information to the Task Builder: 


/MM indicates that the core image of the common block will 
reside on a system with Memory Management. 


/PI indicates that the core image is position independent; 
that is, the virtual address of the common block may 
appear on any 4K boundary within a task's address 
space. 


/-HD indicates that the core image will not contain a 
header. A header is’ only required for a core image 
file that is to be installed and executed as a task. 


The names of the partition, task file, and symbol-table files must 
agree. 


The STACK option must be used to eliminate the stack space. 


The following sequence illustrates the corresponding procedure for an 
unmapped system: 


>SET /UIC=[1,1] 

>TKB 
TKB>UDCOM/-MM, LP: ,SY: UDCOM/PI/—-HD=[200, 200] UDCOM 
TKB>/ 

ENTER OPTIONS: 

TKB>STACK=0 

TKB>PAR=UDCOM:171000:1000 

TKB>/ 


Again the task builder is requested to produce a core image and symbol 
table file under the UIC [1,1], and a map file on the line printer 
from the input file UDCOM.OBJ. The output file switches convey the 
following information: 


/-MM indicates that the core image of the common block will 
reside on an unmapped system. 


/PI Indicates that the core image is position independent. 
In an unmapped system, the core image is fixed in the 
same address space for all tasks; however, the global 
symbols defined in the symbol table file retain the 
relocatable attribute. 


/-HD indicates that a core image without a header is to be 
created. 


The PAR option specifies the base and length of the common area _ to 
coincide with the standard UDCl1l addresses in the IYO page. All 
references to the common block by tasks will be resolved within this 
region. 


15.4.3.2 Making the Common Block Resident - The following SET command 
creates a UDC11 common block residing in the I/O page for a mapped 
system: 


>SET /MAIN=UDCOM:7710:10:DEV 
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The corresponding command in an unmapped system is: 
>SET /MAIN=UDCOM:1710:10:DEV 


The preceding sequence specifies the allocation of a common block in 
the I/O page whose physical address limits correspond to the UDC11 
standard locations. Note that the address bounds and length are 
defined in units of 32 words. 


The command 
>INS [1,1]UDCOM 


declares the common block resident in the system. 


15.4.3.3 Linking a Task to the UDC11 Common Block - A task may access 
UDC11 modules by linking to the common block as follows: 


TKB>TASK, LP: =TASK. OBJ 
TKB>/ 

ENTER OPTIONS: 

TKB> COMMON=UDCOM: RW 
TKB>/ 


The above sequence is valid for either a mapped or unmapped system. 
In both cases the Task Builder will link the task to the common block 
by resolving references to the Global symbol definitions contained in 
UDCOM.STB. If memory management is present, the Executive will map 
the appropriate physical locations into the task's virtual addressing 
space when the task is made active. 


15.5 FORTRAN INTERFACE 
A collection of FORTRAN-callable subroutines provide FORTRAN programs 
access to the UDC12. These are described in this section. All are 
reentrant and may be placed in a resident library. 
Instead of using the FORTRAN-callable subroutines described in this 
section, a FORTRAN program may use the global common feature described 
in Section 15.4 to reference UDC11 modules directly in the I/O page, 
as shown in the following example: 
Cc 
Cc UDC11 GLOBAL COMMON 
Cc 
COMMON /UDCOM/ ICSM(10) ,IAO(10) 
Cc 
¢ READ CONTACT SENSE MODULE i DIRECTLY 
Cc 
ICS=ICSM(1) 


Note that the position of each module type must correspond to the 
sequence in which storage is allocated in the common statements. 
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15.5.1 Synchronous and Asynchronous Process Control I/0 


The ISA standard provides for synchronous and asynchronous’ process 
T/0% Synchronous 1/0 is indicated by appending a "W" to the name of 
the subroutine (for example, AO/AOW). But due to the fact that nearly 
all UDC11 I/0 operations are performed immediately, in most cases the 
"W" form of the call is retained only for compatibility and has no 
meaning under RSX-11M. In the case of A/D input, however, the "W" 
form is significant: The synchronous call suspends task execution 
until input is complete. If the asynchronous form is used, execution 
continues and the calling program must periodically test the status 
word for completion. 


15.5.2 The isb Status Array 


The isb (I/O status block) parameter is a 2-word integer array that 
contains the status of the FORTRAN call, in accordance with ISA 
(Instrument Society of America) convention. This array serves’ two 
purposes: 


1. It is the 2-word I/O status block to which the driver returns 
an I/O status code on completion of an I/O operation. 


2. The first word of isb receives a status code from the FORTRAN 
interface in ISA-compatible format, with the exception of the 
I/O pending condition, which is indicated by a status of 0. 
The ISA standard code for this condition is +2. 


The meaning of the contents of isb varies, depending on the FORTRAN 
call that has been executed; but Table 15-4 lists certain general 
principles that apply. The section describing each subroutine gives 
more details. 


In some cases, the values or states of points being read, pulsed, or 
latched are returned to isb word 2. 


FORTRAN interface subroutines for analog input depend on asynchronous 


system traps to set their status. Thus, if the trap mechanism is 
disabled, proper status cannot be set. 


Table 15-4 
Contents of First Word of isb 


isb(1) 0 Operation pending; I/0 in progress 


isb(1) Successful completion 


isb(1) Interface subroutine unable to generate 
QIO directive or number of points 


requested is zero 


3 < isb(1) < 300 QIO directive rejected and actual error 


code = ~(isb(ij) - 3) 
isb(1) > 300 Driver rejected request and actual 
error code = -(isb(1) - 300) 


Dee cot en ar Se tc a ee a eee eee ee 
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For direct access calls (indicated in Table 15-5 below), errors are 
detected and returned by the FORTRAN interface subroutine itself, 
rather than by the driver. Although the use of a 2-word status’ block 
is therefore unnecessary, these errors are returned in standard format 
to retain compatibility with functions called through QIO directives 
and handled by other drivers. Errors of this type that may be 
returned are: 


isb(1) = 3 Number of points requested is 
0 
isb(1) = +321 Invalid UDC11 module 


15.5.3 FORTRAN Subroutine Summary 

Table 15-5 lists the FORTRAN interface subroutines supported for the 
UDC11 under RSX-11M. (D) indicates a direct access call, and the 
optional logical unit number for such a call may be _ specified to 
retain compatibility with RSX-11D; but this specification is ignored 
by RSX-11M. 

~The following subsections briefly describe the function and format of 
each FORTRAN subroutine call. Note the use of ASUDLN to specify a 
default logical unit number. Also consider the numbering conventions 
described in 15.7.2. 


The following FORTRAN functions do not perform I/O directly, but 
facilitate conversions between BCD and binary. 


Convert four BCD digits to a binary number: 
IBIN = KBCD2B(IBCD) 

Convert a binary number to four BCD digits: 
IBCD = KB2BCD(IBIN) 


Table 15-5 
FORTRAN Interface Subroutines for the UDC11 


AIRD/AIRDW Perform input of analog data in = random 
sequence 
AISQ/AISQW Read a series of sequential analog input 
| channeis 
AO/AOW Perform analog output on several channels 
(D) 
ASUDLN Assign a LUN to the UDC11 
| 


| CTDI | Connect a circular buffer to receive |! 
| contact interrupt data | 


(continued on next page) 
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Table 15-5 (Cont.) 
FORTRAN Interface Subroutines for the UDC11 


CTTI 


Function 


Connect a circular buffer to receive 
timer interrupt data 


Disconnect a buffer from contact 
interrupts 


DFDI 


DFTI Disconnect a buffer from timer interrupts 


Read several 16-point contact sense 
fields (D) 


DI/DIW 


DOL/DOLW Latch or unlatch several 16-point fields 

DOM/DOMW Pulse several 16-point fields (D) 
interrupt point (D) 

RDCS Read the contents of a contact interrupt 
circular buffer, returning data on only 
those points that have changed state 

RDDI Read the contents of a contact interrupt 
circular buffer, one point for each call 

RDTI Read the contents of a timer interrupt 


RCIPT Read the state of a single contact 
circular buffer, one entry for each call 


Read the contents of a contact interrupt 
circular buffer, returning 16 bits of 
module data and change-of-state 
information 


Read a single timer module (D) 


Set a timer module to an initial value 


15.5.4 AIRD/AIRDW: Performing Input of Analog Data in Random Sequence 


The ISA standard AIRD/AIRDW FORTRAN subroutines input analog data in 
random sequence. These calls are issued as follows: 


AIRD 


CALL (inm,icont,idata,[isb] ,lun) 


AIRDW 


inm 


The number of analog input channels. 
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icont 
An integer array containing terminal connection data-channel 


number (right-justified in bits 0-11) and gain (bits 12-15), as 
shown in Table 15-3. 


idata 


An integer array to receive the converted values. 


isb 

A 2-word integer array to which the subroutine status is 

returned. 
lun 

The logical unit number. 

NOTE 
lun is a required parameter. 

The isb array has the standard meaning defined in Section 15.5.2. LE 
inm = 0, then isb(1) = 3. The contents of idata are undefined if an 


error occurs. 


15.5.5 AISQ/AISQW: Reading Sequential Analog Input Channels 


The ISA standard AISO/AISQW FORTRAN subroutines read a series of 
sequential analog input channels. These calls are issued as follows: 


AISQ 
CALL (inm,icont,idata,[isb] ,lun) 


AISQW 
inm 
The number of analog input channels. 
icont 
An integer array containing terminal connection data-channel 
number (right-justified in bits 0-11) and gain (bits 12-15), as 
shown in Table 15-3. 
idata 


An integer array to receive the converted values. 
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isb 
A 2-word integer array to which the subroutine status is 
returned. 

lun 


The logical unit number. 


NOTE 


lun is a required parameter. 


For sequential analog input, channel number is computed in steps of 
one, beginning with the value specified in the first element of icont. 
The channel number field is ignored in all other elements of the 
array. 


The gain used for each conversion is taken from the respective element 
in icont. Thus, even though the channel number is ignored in all but 
the first element of icont, the gain must be specified for each 
conversion to be performed. 


The isb array has the standard meaning defined in Section 15.5.2. Tf 


inm = 0, then isb(1) = 3. The contents of idata are undefined if an 
error occurs. 


15.5.6 AO/AOW: Performing Analog Output 
The ISA standard AO/AOW FORTRAN subroutines initiate analog output on 


several channels. These calls are issued as follows: 


AO 
CALL (inm,icont,idata,[isb],[lun]) 
AOW 


inm 

The number of analog output channels. 
icont 

An integer array containing the channel numbers. 
idata 


An integer array containing the output voltage settings, in _ the 
range 0-1023. 
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isb 
A 2-word integer array to which the subroutine status is 
returned. 

lun 


The logical unit number (ignored if present). 


The isb array has the standard meaning defined in Section 15.5.2. 


15.5.7 ASUDLN: Assigning a LUN to the UDC1l1 


The ASUDLN FORTRAN subroutine assigns the specified LUN to the 
specified unit and defines it as the default logical unit number to be 
used whenever a LUN specification is omitted from a UDC1l1 subroutine 
call. It is issued as follows: 


CALL ASUDLN (lun,[fisw],[iun] ) 


lun 
The logical unit number to be assigned to the specified unit, and 
defined as the default. 

isw 
An integer variable to which the result of the ASSIGN LUN’ system 
directive is returned. 

iun 


An integer defining the UDC11 unit number. If no number is 
specified, 0 is assumed. 


15.5.8 CTDI: Connecting to Contact Interrupts 
The CTDI FORTRAN subroutine connects a task to contact interrupts and 
specifies a circular buffer to receive contact interrupt data. The 
length of this buffer can be computed by considering the following: 

e Rate at which contact module interrupts occur 


e Number of modules that can interrupt simultaneously 


® Rate at which the circular buffer is emptied 
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The UDC1l1l driver generates a 5-word entry for each contact interrupt 
and the interface subroutine itself requires 10 words of additional 
Storage. Thus the isz parameter, described below, can be computed as 
follows: 

isz = (10 + 5 ¥* n) 


where n is the number of entries in the buffer and isz is expressed in 
words. 


The call is issued as follows: 


CALL CTDI (ibuf,isz,iev,[isb],[lun]) 


ibuf 


An integer array that is to receive contact interrupt data. 


isz 


The length of the array in words, with a minimum size of 15. 


iev 
The trigger event flag number. The specified event flag is set 
whenever the driver inserts an entry in the data buffer. 

isb 
A 2-word integer array to which the subroutine status is 
returned. 

lun 
The logical unit number. 


The isb array has the standard meaning defined in Section 15.5.2. 


15.5.9 CTTI: Connecting to Timer Interrupts 
The CTTI FORTRAN subroutine connects a task to timer interrupts 9 and 
specifies a circular buffer to receive timer interrupt data. The 
length of this buffer can be computed by considering the following: 

e Rate at which timer module interrupts occur 


e Number of modules that can interrupt simultaneously 


e Rate at which the circular buffer is emptied 
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The UDC11l driver generates a 4-word entry for each timer interrupt and 
the interface subroutine itself requires 8 words of additional 
storage. Thus the isz parameter, described below, can be computed as 
follows: 

isz = (8 + 4 * n) 


where n is the number of entries in the buffer and isz is expressed in 
words. 


When a timer module interrupt occurs, the driver resets the count to 
an initial value, normally that specified in iv. The initial value 
for a specific module can be modified by calling the CTI subroutine 
(see Section 15.5.19). 

The call is issued as follows: 


CALL CTTI (ibuf,isz,iev,iv,[isb],[lun]) 


ibuf 

An integer array that is to receive timer interrupt data. 
isz 

The length of the array in words, with a minimum size of 12. 
iev 


A trigger event flag number. The specified event flag is set 
whenever the driver inserts an entry in the data buffer. 


iv 
An integer array that contains the initial timer module values, 
with one entry for each timer module, where entry n corresponds 
to timer module number n-l. 

isb 
A 2-word integer array to which the subroutine status is 
returned. 

lun 


The logical unit number. 


The isb array has the standard meaning defined in Section 15.5.2. 


15.5.10 DFDI: Disconnecting from Contact Interrupts 


The DFDI FORTRAN subroutine disconnects a task from contact 
interrupts. It is issued as follows: 


CALL DFDI ([fisb],[lun]) 
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isb 


A 2-word integer array to which the subroutine status is 
returned. 


lun 
The logical unit number. 


The isb array has the standard meaning defined in Section 15.5.2. 


15.5.11 DFTI: Disconnecting from Timer Interrupts 


The DFTI FORTRAN subroutine disconnects a task from timer interrupts. 
It is issued as follows: 


CALL DFTI ([isb],flun]) 


isb 
A 2-word integer array to which the subroutine status is 
returned. 

lun 
The logical unit number. 


The isb array has the standard meaning defined in Section 15.5.2. 


15.5.12 DI/DIW: Reading Several Contact Sense Fields 
The ISA standard DI/DIW FORTRAN subroutines read several 16-point 


contact sense fields. These calls are issued as follows: 


DI 

CALL (inm,icont,idata,isb, [lun] ) 
DIW 

inm 


The number of fields to be read. 


icont 
An integer array containing the initial point number of each 
field to be read. 

idata 


An integer array that is to rec 


e he input data, 16 bits of 
contact data for each field read. 
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isb 
A 2-word integer array to which the subroutine status 
returned. 

lun 
The logical unit number (ignored if present). 


The isb array has the standard meaning defined in Section 15.5.2. 


15.5.13 DOL/DOLW: Latching or Unlatching Several Fields 


The ISA standard DOL/DOLW FORTRAN subroutines latch or unlatch one 
more 16-point fields. These calls are issued as follows: 


DOL 
CALL (inm,icont,idata,imsk,[isb], [lun] ) 
DOLW 


inm 


The number of fields to be latched or unlatched. 


icont 


An integer array containing the initial point number of 
16-point field. 


idata 


An integer array that specifies the points to be _ latched 


is 


or 


each 


or 


unlatched; bit n of idata corresponds to point number icont + n; 


if the corresponding bit in imsk is set, the bit is changed; 


a 


bit value of 1 indicates latching, and 0 unlatching; each entry 


in the array specifies a string of 16 points. 


imsk 


An integer array in which bits are set to indicate points whose 


states are to be changed in the corresponding idata bits; 
entry in the array specifies a 16-bit mask word. 
isb 


A 2-word integer array to which the subroutine’ status 
returned. 


lun 
The logical unit number. 


The isb array has the standard meaning defined in Section 15.5.2. 
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15.5.14 DOM/DOMW: Pulsing Several Fields 


The ISA standard DOM/DOMW FORTRAN subroutines pulse several 16-bit 
fields (l-shot digital output points). These calls are issued as 
follows: 


DOM 
CALL (inm,icont,idata,lidx],[isb],[lun]) 
DOMW 


inm 
The number of fields to be pulsed. 

icont 
An integer array containing the initial point number of each 
16-point field. 

idata 
An integer array which specifies the points to be pulsed; bit n 
of idata corresponds to point number icont + n. 

idx 
A dummy argument retained for compatibility with existing 
Instrument Society of America standard FORTRAN process control 
calls. 

isb 
A 2-word integer array to which the subroutine status is 
returned. 

lun 


The logical unit number (ignored if present). 


The isb array has the standard meaning defined in Section 15.5.2. 


15.5.15 RCIPT: Reading a Contact Interrupt Point 


The RCIPT FORTRAN subroutine reads the state of a single contact 
interrupt point. It is issued as follows: 


CALL RCIPT (ipt,isb,[lun]) 
ipt 
The number of the point to be read; points are numbered 


sequentially from 0, the first point on the first contact 
interrupt module. 
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isb 
A 2-word integer array to which the subroutine status is 
returned. 

lun 
The logical unit number (ignored if present). 

The isb array has the same basic meaning defined in Section 15.5.2. 


However, isb word 2 is set to one of the following values, 
representing the state of the point: 


Setting Meaning 
.FALSE. (0) Point is open. 
«TRUBS “Ad) Point is closed 

NOTE 


To increase throughput, the subroutines 
RDCS, RDDI, RDTI, and RDWD described in 
the following four sections do not issue 
the clear Event Flag directive until a 
buffer-empty condition is detected. The 
calling task, therefore, must avoid 
issuing a Wait-For directive until a 
buffer-empty is reported. 


15.5.16 RDCS: Reading Contact Interrupt Change-of-State Data from a 
Circular Buffer 


The RDCS FORTRAN subroutine reads contact interrupt data from a 
circular buffer that was specified in a CTDI call (see Section 
15.5.8). It does no actual input or output, but rather performs a 
point-by-point scan of an interrupt entry in the buffer, returning the 
State of each point that has changed state as a logical value. The 
trigger event flag that was specified in the CTDI call is cleared when 
the "buffer empty" condition is detected. 


On the initial call to RDCS, the module number, module data, and 
change-of-state word of the next interrupt entry are read from the 
circular buffer and stored for subsequent reference. The subroutine 
then searches the entry change-of-state word until a nonzero point is 
encountered. The point number is computed and returned to the caller 
along with the state of the point. Scanning for points that have 
changed state resumes on the next call; all other points are 
bypassed. The next entry is automatically read when the caller has 
received all change-of-state information from the current entry. If a 
valid entry is not found, ipt is set negative and ict (if specified) 
is either assigned a value of O or an overrun count maintained by the 
UDC11l driver. If ict is 0, no further entries remain. A nonzero 
value indicates that the driver received more data than could be 
stored in the buffer, and ict represents the number of entries that 
were discarded. 
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The RDCS call is issued as follows: 


CALL RDCS (ipt,ival,[ict]) 


ipt 

A variable to which the digital input point number is returned; 

it may be set as follows: 

e ipt 0Oif no valid entry is found (that is, no interrupt data 
currently in buffer, or overrun detected). One of the 
following values is returned to indicate the condition 
detected: 

-l1 = Buffer empty 
-2 = Overrun detected 

e ipt => 0 if the value indicated is a point number that has 
changed state; the state is returned to ival. 

ival 

A variable to which the state of the point is returned; it may 

be set as follows: 

e .FALSE. (0) if the point is open 

e .TRUE. (-1) if the point is closed 

ict 


An integer variable for receiving the overrun count. A nonzero 
positive count indicates that the driver was unable to store the 
number of interrupts indicated. 


15.5.17 RDDI: Reading Contact Interrupt Data from a Circular Buffer 


The RDDI FORTRAN subroutine reads contact interrupt data from a 
circular buffer that was specified in a CTDI call (see Section 
15.5.8). It does no actual input or output, but rather performs a 
point-by-point scan of an interrupt entry in the buffer, returning the 
state of each point as a logical value. The trigger event flag that 
was specified in the CTDI call is also cleared. 


On the initial call to RDDI, the module number and data of the next 
interrupt entry are read from the circular buffer and stored for 
subsequent reference. The subroutine then sets the current data bit 
number n to 0, examines the state of data bit n, and converts bit n to 
a point number by the following formula: 


ipt = module number * 16 +n 
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On each subsequent call, n is incremented by one and then data bit n 
is examined in the stored module data. Whenn reaches 16, it is reset 
to 0 and an attempt is made to read the next interrupt entry from the 
circular buffer. If a valid entry is not found, ipt is set negative 
and ict (if specified) is either assigned a value of 0 or an _ overrun 
count maintained by the UDC11 driver. If ict is 0, no further entries 
remain. A nonzero value indicates that the driver received more data 
than could be stored in the buffer, and ict represents the number of 
entries that were discarded. 


The RDDI call is issued as follows: 


CALL RDDI (ipt,ival,[ict]) 


ipt 
A variable to which the digital input point number is’ returned; 


it may be set as follows: 


e ipt 0 if no valid entry is found (that is, no interrupt data 
currently in buffer, or buffer empty). One of the following 
values is returned to indicate the condition detected: 


-l=Buffer empty 
-2=Overrun detected 


e ipt => 0 if the value indicated is a point number; the _ state 
is returned to ival 


ival 
A variable to which the state of the point is returned; it may 
be set as follows: 
e .FALSE. (0) if the point is open 
e .TRUE. (-1) if the point is closed 
Lee 


A variable to which the overrun count may be returned; a nonzero 
positive count indicates that the driver was unable to store the 
number of entries indicated. 


15.5.18 RDTI: Reading Timer Interrupt Data from a Circular Buffer 


The RDTI FORTRAN subroutine reads timer interrupt data from a circular 
buffer that was specified ina CTTI call (see Section 15.5.9). It 
does no actual input or output, but rather performs a scan of each 
entry in the buffer, returning the timer value for each call. The 
trigger event flag that was specified in the cCTTI call is also 
cleared. 


When a timer module interrupt occurs, the UDC11 driver resets’ the 
count to an initial value, usually that specified in the iv array on 
the CTTI call. The initial value can be modified for a_ specific 
module by calling the subroutine SCTI (see Section 15.5.19). 
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The RDTI call is issued as follows: 


CALL RDTI (imod,itm,[ivrn] ) 


imod 

A variable to which the module number is returned; it may be set 

as follows: 

e imod 0 if no valid entry is found (that is, no interrupt data 
currently in buffer, or buffer empty). One of the following 
values is returned to indicate the condition detected: 

-~l=Buffer empty 
-2=Overrun detected 

e imod > 0 if the entry is valid, indicating a module number; 
the value of the timer module is returned in itm 

itm 

A variable to which the timer value is returned. 

ivrn 


A variable to which the overrun count may be returned; a nonzero 
positive count indicates that the driver was unable to store the 
number of values indicated. 


15.5.19 RDWD: Reading a Full Word of Contact Interrupt Data from the 
Circular Buffer 


The RDWD FORTRAN subroutine reads a full word of contact interrupt and 
change-of-state data from the circular buffer that was specified in a 
CTDI call (see Section 15.5.8). It does no actual input or output, 
but rather performs a scan of each entry, returning the state of a 
module and, optionally, the change-of-state data for each call. The 
trigger event flag specified in the call to CTDI is cleared. 


The call to RDWD is issued as follows: 


CALL RDWD (imod,ist,livrn],[icos]) 


imod 


A variable to which the module number is returned; it may be set 
as follows: 


@e imod 0 if no valid entry is found (that is, no interrupt data 
currently in buffer .or overrun detected). One of the 
following values is returned to indicate the condition 
detected: 


-l=Buffer empty 
-2=Overrun detected 
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ist 
A variable to which the module data is returned. 


ivrn 


A variable to which the overrun count may be returned; 


a 


nonzero, poSitive count indicates that the driver was unable to 


store the number of entries indicated. 


icos 


A variable to which the change-of-state data is returned. 


One 


bit is set for each point that has changed state in the direction 
indicated by the "point open" (POP) or "point closed" (PCL) 


jumpers on the module. 


15.5.20 RSTI: Reading a Timer Module 


The RSTI FORTRAN subroutine reads a single timer module. It is issued 


as follows: 


CALL RSTI (imod,isb, [lun] ) 


imod 


The module number of the timer to be read. 


isb 


A 2-word integer array to which the subroutine status 
returned. 


lun 
The logical unit number (ignored if present). 


The isb array has the standard meaning defined in Section 15.5.2. 


15.5.21 SCTI: Initializing a Timer Module 


is 


The SCTI FORTRAN subroutine sets a timer module to an initial value. 


It is issued as follows: 


CALL SCTI (imod,ival,[{isb], [lun] ) 


imod 


The module number of the timer to be set. 
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ival 


The initial timer value. 


isb 
A 2-word integer array to which the subroutine status is 
returned. 

lun 
The logical unit number. 

The isb array has the standard meaning defined in Section 15.5.2. 


Calls to initialize a counter are valid only if the issuing task has 
connected a buffer for receiving counter interrupts by a call to CTTI. 


15.6 STATUS RETURNS 
Table 15-6 lists the error and status conditions that are returned by 


the UDC1l1 driver described in this chapter: 


Table 15-6 
UDC11 Status Returns 


IS.SUC Sucessful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the I/0 
Status block can be examined to determine the number 
of samples completed or converted. 


IS.PND I/O request pending 
The operation specified in the QIO directive has not 
yet been executed. The I/O status block is filled 
with Os. 

TE.ABO Operation aborted 


The specified I/O operation was canceled with I0.KIL 
while still in the I/O queue. 


TE.BAD Bad parameter 


An illegal specification was supplied for one or more 
of the device-dependent QIO parameters (words 6-11). 
For the UDCll, this code indicates an illegal channel 
number or gain code for the ADUO1. 


(continued on next page) 
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IE.BYT 


IE.CON 


IE.DNR 


IE.IEF 


Tee LPC 


IE.MOD 


IE.OFL 
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Table 15-6 (Cont.) 
UDC11 Status Returns 


Byte-aligned buffer specified 


Byte alignment was specified for a buffer but only 
word alignment is legal for the UDC12. Alternately, 
the length of a buffer was not an even number of 
bytes. 


Connect error 


The task attempted to connect to contact or timer 
interrupts, but the interrupt was already connected 
to another task. Only one task can be connected to a 
timer or contact interrupt. Alternately a task which 
waS not connected attempted to disconnect from 
contact or timer interrupts. 


Device not ready 


The physical device unit specified in the QIO 
directive waS not ready to perform the desired I/0 
operation. For the ADUO], this code is returned if 
an interrupt time out occurred or the power failed. 


Invalid event flag number 


An invalid trigger event flag number was specified in 
a connect function. 


Tllegal function 


A function code was included in an I/O request that 
is illegal for the UDC11l, or a request to initialize 
a counter (IO.ITI) was issued by a task that was not 
connected to receive counter interrupts. The 
function may also refer to a UDC11 feature which was 
not specified at system generation. 


Invalid UDC11 module 

On latching output, the user specified a starting 
point number that was not legal (defined at system 
generation) or was not evenly divisible by 16. 


Device off line 


The physical device unit associated with the LUN 
specified in the QIO directive was not on line. When 
the system was booted, a device check indicated that 
this physical device unit was not in the 
configuration. 


(continued on next page) 
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Table 15-6 (Cont.) 
UDC11 Status Returns 


Reason 


IE.PRI Privilege violation 


The task which issued the request was not privileged 
to execute that request. For the UDCl1, this code 
indicates that a checkpointable task attempted to 
connect to timer or contact interrupts. 


IE.SPC Tllegal address space 


partially or totally outside the address space of the 
issuing task. Alternately, the interrupt buffer was | 
too small for a single data entry (six words for 
timer interrupts and seven words Eor contact 
interrupts), or a byte count of 0 was specified. 


| The specified control, data, or interrupt buffer was | 


FORTRAN interface values for these status returnS are presented in 
Section 15.6.1. 


15.6.1 FORTRAN Interface Values 


The values listed in Table 15-7 are returned in FORTRAN’ subroutine 
calls. 


Table 15-7 
FORTRAN Interface Values 


Status Return FORTRAN Value 


IS.SUC 

IS.PND 

ITE.ABO 

IE.ADP 

ITE.BAD 

TE.BYT ro 
IE. DAO +313 
IE.DNR +303 
IE.IEF +100 
IE.IFC #302 
IE. ILU oO 
IE.MOD +321 
IE.ONP +305 
IE.PRI +316 
ITE.RSU tools 
IE.SDP +102 
IE.SPC +306 
IE.ULN +08 


| IE.UPN | +04 | 
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15.7 PROGRAMMING HINTS 


This section contains information on important programming 
considerations relevant to users of the UDC11 driver described in this 
chapter. 


15.7.1 Numbering Conventions 


Numbering is relative. Module numbers start at 0, beginning with the 
first module of a given type. 


Channel numbers also start at 0, with channel 0 as the first channel 
on the first module of a given type. For the ADUO1, channel 8 is the 
first channel on the second analog output module. 


Each IAD-IA module installed in an ICS11 subsystem occupies 120 
channels (regardless of the number of multiplexers installed). In 
this case, channel 120 is the first channel on the second IAD-IA A/D 
converter. 


Point numbers start at 0, with point 0 as the first point on the first 
module of a given type. For instance, point 20(8) is the first point 


of the second contact sense module (that is, relative module number 
1 ae 


15.7.2 Processing Circular Buffer Entries 
Circular buffer entries should be processed in the following sequence. 
1. Execute a WAITFOR system directive using the trigger event 
flag specified in the subroutine called to connect the 
circular buffer (CTTI or CTDI). 
2. Repeatedly call the appropriate subroutine to read _ the 
circular buffer until all entries have been obtained and ipt 
indicates that the buffer is empty (-l). 


3. Perform any other processing and return to step l. 
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16.1 INTRODUCTION 


The LPS11 and AR11 Laboratory Peripheral Systems are modular, 
real-time subsystems used for the acquisition and/or output of 
laboratory analog data. (Laboratory Peripheral Systems drivers are 
not supported on RSX-11M-PLUS systems.) Table 16-1 compares the LPS11 
with the ARI11. 


Table 16-1 
Laboratory Peripheral Systems 


Analog-to-Digital Conversion | 12 bits of precision 10 bits of precision 
(with Sample and Hold 16-channel multiplexer 16-channel multiplexer 
Circuitry) with gain ranging without gain ranging 


| Maximum of 64 channels 
without gain ranging 


Programmable Real-Time Clock / Yes Yes 
Digital-to-Analog Output 12 bits of precision 10 bits of precision 
10 channels (includ- 2 channels (including 


ing display) display) 


Display Control 4096 by 4096 dot matrix | 1024 by 1024 dot matrix 


Digital I/O Option 16 digital points 16 digital points 
and programmable (available with 
relays DR11-K option) 


At system generation, the user can specify the following: 
e The number of A/D channels 
e The presence or absence of the gain-ranging option (LPSAM-SG) 
(LPS11 only) and the polarity of each channel (uni- or 
bipolar) 


e The presence or absence of the external D/A option (LPSVC and 
LPSDA), and if present, the number of D/A channels 


e The clock preset value 
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16.1.1 AR11 Laboratory Peripheral System 


The AR11 is a l-module, real-time analog subsystem that interfaces to 
the PDP-11 family of computers by a "hex" small peripheral controller 
slot. The system is a subset of the LPS11 and, as such, enjoys’ the 
Same degree of flexibility. The AR11 includes a 16-channel, 10-bit 
A/D converter with sample-and-hold, a programmable real-time clock 
with one external input, and a display control with two 10-bit D/A 
converters. 


16.1.2 LPS11 Laboratory Peripheral System 


The LPS11 is a high-performance, modular, real-time subsystem with the 
flexibility of serving a variety of applications, including biomedical 
research, analytical instrumentation, data collection and_ reduction, 
monitoring, data logging, industrial testing, engineering, and 
technical education. The basic subsystem, built in a compact size and 
designed for easy interface with external instrumentation, includes a 
13-bit A/D converter, a programmable real-time clock, with two Schmitt 
triggers, a display controller with two 12-bit D/A converters, and a 
16-bit digital I/O option. Up to nine different option types may be 
added to the basic package. 


16.2 GET LUN INFORMATION MACRO 


If a GET LUN INFORMATION system directive is issued for a_ LUN 
associated with a Laboratory Peripheral System, word 2 (the first 
characteristics word) contains all Os words 3 and 4 are undefined, and 
word 5 contains a 16-bit buffer preset value that controls the rate of 
the real-time clock interrupts, as explained in Section 16.6.1. 


16.3 QI0O MACRO 


This section summarizes standard and device-specific QIO functions for 
the Laboratory Peripheral System drivers. 


16.3.1 Standard QIO Function 
Table 16-2 lists the standard function of the QIO macro that is valid 
for the Laboratory Peripheral Systems. 


Table 16-2 
Standard QIO Function for 
Laboratory Peripheral Systems 


ee eee 
oe TO; KEL << | Cancel I/0 coe 


IO.KIL cancels all queued and in-progress I/O requests. 
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16.3.2 Device-Specific QIO Functions (Immediate) 


Except for IO.STP (see Section 15.3.4), all device-specific functions 
of the QIO macro that are valid for the Laboratory Peripheral Systems 
are either immediate or synchronous. Each immediate function performs 
a complete operation, whereas each synchronous’ function simply 
initiates an operation synchronized to the real-time clock. Table 
16-3 lists the immediate functions. 


Table 16-3 
Device-Specific QIO Functions for the 
Laboratory Peripheral Systems (Immediate) 


Format Function 


LOSERD (<4,25<1 ur DISPLAY number in LED 
(LPS11 only) 


IO.REL,...,<rel,pol> LATCH output relay (LPS11 only) 
IO.SDI,...,<mask> READ digital input register 
IO0.SDO,...,<mask,data> WRITE digital output register 
int 
The 16-bit signed binary integer to display. 
num 
The LED digit number where the decimal point is to be placed. 
rel 
The relay number (0 or 1). 
pol 
The polarity (0 for open, nonzero for closed). 
mask 
The mask word. 
data 


The data word. 


The following subsections describe the functions listed above. 
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16.3.2.1 I0.LED - This LPSll-only function displays a 16-bit signed 
binary integer in the light-emitting diode (LED) lights. The number 
is displayed with a leading blank (positive number) or minus” sign 
(negative number), followed by five non-zero-suppressed decimal digits 
that represent the magnitude of the number. LED digits are numbered 
from right to left, starting at l. 


The number may be displayed with or without a decimal point. Tf the 
parameter num is a number’ from 1 to 5, then the corresponding LED 
digit is displayed with a decimal point to the right of the digit. If 
the LED digit number is not a number from 1 to 5, then no decimal 
point is displayed. 


16.3.2.2 I0O.REL - This LPSll-only function opens or closes the 
Programmable relays in the digital I/O status register. Approximately 
300 milliseconds are required to open or close a relay. The driver 
imposes no delays when executing this function. Thus it is the 
responsibility of the user to insure that adequate time has’ elapsed 
between the opening and closing of a relay. 


16.3.2.3 I0O.SDI - This function reads data qualified by a mask word 
from the digital input register. The mask word contains a 1 in each 
bit position from which data is to be read. All other bits are zero 
filled and the resulting value is returned in the second I/O status 
word. 

The operation performed is: 


RETURN VALUE=MASK.AND.INPUT REGISTER 


16.3.2.4 I10.SDO - This function writes data qualified by a mask word 
into the digital output register. The mask word contains a 1 in each 
bit position that is to be written. The data word specifies the data 
to be written in corresponding bit positions. 

The operation performed is: 


NEW REGISTER=<MASK.AND.DATA>.OR.<<.NOT.MASK>.AND.OLD REGISTER> 


16.3.3 Device-Specific QIO Functions (Synchronous) 


Table 16-4 lists the synchronous, device-specific functions of the QIO 
macro that are valid for the Laboratory Peripheral Systems. 


16-4 


LABORATORY PERIPHERAL SYSTEMS DRIVERS 


Table 16-4 
Device-Specific QIO Functions for the 
Laboratory Peripheral Systems (Synchronous) 


QIOSC IO.ADS,...,<stadd,size,pnt, 
ticks,bufs,chna> 


INITIATE A/D sampling 


IO.HIS,...,<stadd,size,pnt, 
ticks,bufs> 


INITIATE histogram sampling 
(LPS11 only) 


QTOSC IO.MDA,...,<stadd,size,pnt, 


INITIATE D/A output 


ticks,bufs,chnd> | 
QIOSC IO.MDI,...,<stadd,size,pnt, INITIATE digital input | 
ticks,bufs,mask> sampling 
QIOSC IO.MDO,...,<stadd,size,pnt, INITIATE digital output 


ticks,bufs,mask> 


stadd 


The starting address of the data buffer (must be on ae word 
boundary). 


size 
The data buffer size in bytes (must be greater than 0 and a 
multiple of four bytes). 

pnt 
The digital point numbers (byte 0 - starting input/output point 
number; byte 1 - input point number to stop the function). 
Points are numbered from 0 to 15, allowing a maximum of 16 points 
to be specified. 

ticks 
The number of real-time clock ticks between samples or data 
transfers, aS appropriate. 

bufs 


The number of data buffers to transfer. 
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chna 
The analog-to-digital conversion specification. Byte 0 contains 
the starting channel number. For LPS11 this must be in the range 
of 0-63; for AR11 the range is 0-15. If the LPS1l1 gain-ranging 
option is present, the channel number must be in the range of 
0-15, and bits 4 and 5 specify the gain code. 
Byte 1 contains the number of consecutive analog-to-digital 
channels to sample. For LPS11 this must be in the range of 1-64; 
for AR11 or the LPS11 with gain-ranging, the range is 1-16. 

chnd 
The digital-to-analog output channel specification. Byte 0 
contains the starting channel number. For LPS11 this must be in 
the range of 0-9; for the AR11 the range is 0-l. 
Byte 1 contains the number of consecutive channels to be output. 
For LPS11 this must be in the range of 1-10; for AR11 the range 
is 1-2. 

mask 


The mask word. 


The following subsections describe the functions listed above. 


16.3.3.1 1I0.ADS - This function reads one or more A/D channels at 
precisely timed intervals, with or without auto gain-ranging. If two 
or more channels are specified, all are sampled at approximately the 
same time, once per interval. 


Sampling may be started when the request is dequeuved or when a 
specified digital input point is set. A digital output point may 
optionally be set when sampling is’ started. Sampling may be 
terminated by a program request (I0.STP or IO.KIL), by the clearing of 
a digital input point, or by the collection of a specified number of 
buffers of data. 


All input is double buffered with respect to the user task. Each time 
a half buffer of data has been collected, the user task is notified 
(by the setting of an event flag) that data is available to be 
processed while the driver fills the other half of the buffer. If the 
user task does not respond quickly enough, a data overrun may result. 
This occurs if the driver attempts to put another data item in the 
user buffer when no space is available. 


The subfunction modifier bits are identical to those described in 
Section 16.3.3.2. In addition, setting bit 3 to a 1 means LPS11 auto 
gain-ranging is requested. Bit 3 is ignored for the AR11. If bits 7 
and 6 are both set to 1, the digital input point and digital output 
point number are assumed to be the same. 
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If LPS11 auto gain-ranging is used, the LPSAM-SG hardware option must 
be present and specified at system generation. The auto gain-ranging 
algorithm causes a channel to be sampled at the highest gain at which 
Saturation does not occur. If the gain-ranging option is present and 
auto gain-ranging is not specified in bit 3 of the subfunction code, 
then bits 4 and 5 of the starting channel number specify the gain at 
which samples are to be converted. Gain codes are as follows: 


Code Gain 
00 ‘i 
01 4 
10 16 
11 64 


Data words written into the user buffer contain the converted value in 
bits 0-11 and the gain code, as shown below, in bits 12-15: 


Code Gain 
0000 1 
0001 4 
0010 16 
0011 64 


If the LPSAM-SG option is present, then each channel must have been 
defined as uni- or bipolar at system generation. In addition, if 
bandwidth filtering is enabled (and so indicated at system generation 
time), a software delay is imposed by the driver when the multiplexer 
channel is changed. This delay must have been specified at SYSGEN. 


The AR11 always returns data that is equivalent to an LPS11 gain of l. 
Channel polarity must always be specified for the AR11 at system 
generation, since this operation is software selectable at the time 
sampling is initiated. 


16.3.3.2 I0O.HIS - This LPSll-only function measures the elapsed time 
between a series of events by means of Schmitt trigger 1. Each time a 
sample is to be taken, a counter is incremented and Schmitt trigger 1 
is tested. If it has fired, then the counter is written into the user 
buffer and reset to 0. Thus, the data item returned to the user is 
the number of sample intervals between Schmitt trigger firings. 


If the counter overflows before Schmitt trigger 1 fires, then a 0 
value is written into the user buffer. Sampling may be started and 
stopped as described in Section 15.3.3.1. All input is double 
buffered with respect to the user task. 


The subfunction modifier bits appear below. A setting of 1 indicates 
the action listed in the right-hand column. 
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Bit Meaning 
0-3 Unused 
4 Stop on number of buffers 
5 Stop on digital input point clear 
6 Set digital output point at start of operation 
7 Start on digital input point set (a 0 


specification means start immediately). Points 
are numbered from 0 to 15, allowing a maximum of 
16 points to be specified. 


16.3.3.3 IO.MDA - This function writes data into one or more external 
D/A converters at precisely timed intervals. If two or more channels 
are specified, all are written at approximately the same time, once 
per interval. Output may be started or stopped as described in 
Section 16.3.3.1. All output is double buffered with respect to the 
user task. 


D/A converters 0 and 1 correspond to the X and Y registers of the 
display control. Note that there are no specific driver functions to 
set the display status register. This is reserved for the user. D/A 
converters 2 through 9 correspond to the LPS11, LPSDA external D/A 
option. 


The subfunction modifier bits are identical to those described in 
Section 16.3.3.2. 


16.3.3.4 IO.MDI - This function provides the capability to read data 
qualified by a mask word from the digital input register at precisely 
timed intervals. Sampling may be started and stopped as described in 
Section 1643.3.1. All input is double buffered with respect to the 
user task. 


The mask word contains a 1 in each bit position from which data is to 
be read. All other bits are 0. 


The subfunction modifier bits are identical to those described in 
Section 16.3.3.2. 


16.3.3.5 IO.MDO - This function writes data qualified by a mask word 
into the digital output register at precisely timed intervals. Output 
may be started and stopped as described in Section 16.3.3.1. All 
output is double buffered with respect to the user task. 


The subfunction modifier bits are identical to those described in 
Section 16.3.3.2. 
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16.3.4 Device-Specific QIO Function (I0.STP) 


Table 16-5 lists the device-specific function of the QIO macro, which 
is valid for the Laboratory Peripheral Systems. 


Table 16-5 
Device-Specific QIO Function for the 
Laboratory Peripheral Systems (I0.STP) 


a ee 


QTOSC IO.STP,...,<STADD> STOP in-progress request 


stadd 


The buffer address of the function to stop (must be the same as 
the address specified in the initiating request). 


16.3.4.1 I0.STP - IO.STP stops a single, in-progress synchronous 
request. It is unlike IO.KIL in that it cancels only the specified 
request, whereas IO.KIL cancels all requests. 


16.4 FORTRAN INTERFACE 


A collection of FORTRAN-callable subroutines provide FORTRAN programs 
access to the Laboratory Peripheral Systems. These routines are 
described in this section. 


Some of these routines may be called from FORTRAN as either 
subroutines or functions. All are reentrant and may be placed ina 
resident library. 


16.4.1 The isb Status Array 


The isb (I/O status block) parameter is a 2-word integer array that 
contains the status of the FORTRAN call, in accordance with ISA 
convention. This array serves two purposes: 


1. It is the 2-word I/O status block to which the driver returns 
an I/O status code on completion of an I/O operation. 


2. The first word of the isb receives a status code from the 
FORTRAN interface in ISA-compatible format, with the 
exception of the I/O pending condition, which is indicated by 
a status of 0. The ISA standard code for this condition is 
+2. 


The meaning of its contents varies, depending on the FORTRAN call that 
has been executed, but Table 16-6 lists certain general principles 
that apply. The sections describing individual subroutines provide 
more details. 
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Table 16-6 
Contents of First Word of isb 


isb(1) Operation pending; I/0 in progress 


isb(1) Successful completion 


isb(1) Interface subroutine unable to generate QIO 
directive, or illegal time or buffer value 


isb(1) < 300 QIO directive rejected and actual error 
code = -(isb(1) - 3) 


isb(1) > 300 Driver rejected request and actual error 
code = -(isb(l) - 300) 


FORTRAN interface routines depend on asynchronous system traps to. set 
their status. Thus, if the trap mechanism is disabled, proper status 
cannot be set. 


16.4.2 Synchronous Subroutines 
RTS, DRS, HIST (LPS11 only), SDO, and SDAC are FORTRAN subroutines 
that initiate synchronous’ functions. When they are used, the 


appropriate Laboratory Peripheral System driver and the FORTRAN 
program communicate by means of a caller-specified data buffer of the 


following format: 
CURRENT BUFFER POINTER 
ADDRESS OF SECOND !/O STATUS WORD _ | 
ADDRESS OF END OF BUFFER + 1 
ADDRESS OF START OF DATA 


ZK-008-81 


BUFFER HEADER 


START OF DATA 
HALF BUFFER 


END OF BUFFER 


The buffer header is initialized when the synchronous’ function 
initiation routine is called. The length of the buffer must be even 
and greater than or equal to 6. An even length is required so _ that 
the buffer is exactly divisible into half buffers. 


The drivers perform double buffering within the half buffers. Each 
time a driver fills or empties a half buffer, it sets a user-specified 
event flag to notify the user task that more data is available or 
needed. The user task responds by putting more data into the buffer 
or by removing the data now available. 


If the user task does not respond quickly enough, a data overrun may 
result. This occurs if the driver attempts to put another data item 
in the user buffer when no Space is available (that is, the buffer is 
full of data), or if the driver attempts to obtain the next data item 
from the user buffer when none is available (that is, the buffer is 
empty). 
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All synchronous functions can be initiated immediately or when a 
specified digital input point is set (that is, a start button is 
pushed). 


They can be terminated by any combination of a program request, the 
Processing of the required number of full buffers of data, or the 
clearing of a specified digital input point (that is, a stop button is 
pushed). A digital output point may also optionally be set at the 
start of a synchronous function. This could be used, for example, as 
a Signal to start a test instrument. 


16.4.3 FORTRAN Subroutine Summary 
Table 16-7 lists the FORTRAN interface subroutines supported for’ the 


Laboratory Peripheral Systems under RSX-11M. S and F indicate whether 
they can be called as subroutines or functions, respectively. 


Table 16-7 
FORTRAN Interface Subroutines for Laboratory Peripheral Systems 


ADC 


Read a single A/D channel (F,S) 


ADJLPS Adjust buffer pointers (S) 


ASARLN Assign a LUN to ARO: (S) 


ASLSLN Assign a LUN to LSO: (S) 


CVSWG Convert a switch gain A/D value to floating point (F) 
DRS Initiate synchronous digital input sampling (S) 
HIST Initiate histogram sampling (S) (LPS11 only) 
IDIR Read digital input (F,S) 
IDOR Write digital output (F,S) 
IRDB Read data from a synchronous function input buffer 
(F,S) 
LED Display number in LED lights (S) (LPS11 only) 
LPSTP Stop an in-progress synchronous function (S) 
PUTD Put data into a synchronous function output buffer (S) 
RELAY Latch an output relay (S) (LPS11 only) 
RTS Initiate synchronous A/D sampling (S) 
SDAC Initiate synchronous D/A output (S) 
SDO Initiate synchronous digital output (S) 
The £ owing Subsections briefly describe the function and format of 
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16.4.4 ADC: Reading a Single A/D Channel 


The ADC FORTRAN subroutine or function reads a single converted value 
from an A/D channel. If the gain-ranging option is present in the 
LPS11 hardware, the channel may be converted at a specific gain or the 
driver can select the best gain (the gain providing the most 
Significance). The converted value is returned as a normalized 
floating-point number. The call is issued as follows: 


CALL ADC (ichan,[var],figain],[isb]) 


ichan 


The A/D channel to be converted. 


var 
A floating-point variable that receives the converted value in 
floating-point format. 
igain 
The gain at which the specified A/D channel is to be converted. 
The default is 1. If specified, igain may have the following 
values: 
igain Gain 
0 Auto gain-ranging (driver selects gain that 
provides most significance) 
1 i 
2 4 
eo) 16 
4 64 
A gain of 1 is always uSed by the AR11 driver. 
isb 


A 2-word integer array to which the subroutine status is 
returned. 


The isb array has the standard meaning described in Section 16.4.1. 
When the function form of the call is used, the value of the function 
is the same as that returned in var. If this value is negative, an 
error has occurred during the A/D conversion (see Section 16.5.3). 
Otherwise, this value is a floating-point number calculated from the 
following formula: 


var = (64 * converted value) / conversion gain 
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16.4.5 ADJLPS: Adjusting Buffer Pointers 


The ADJLPS FORTRAN subroutine adjusts buffer pointers for a buffer 
that a laboratory peripheral system driver is either synchronously 
filling or emptying. It is usually called when indexing is being used 
for direct access to the data in a buffer. 


When data in a buffer is to be processed only once, the IRDB and PUTD 
routines may be used. In some cases, however, it is useful to leave 
data in the buffer until processing is complete. The user program can 
process the data directly, and then call ADJLPS to free half the 
buffer. Using the routine for synchronous output functions is quite 
similar. When a half buffer of data is ready for output, ADJLPS is 
called to make the half buffer available. 


When ADJLPS is used for either input or output, care must be taken to 
insure that the program stays in syne with the driver. If the program 
loses its position with respect to the driver, the function must be 
stopped and restarted. An attempt to over-adjust will cause a 3 to be 
returned in isb(1l) and no adjustment to take place. 


The call is issued as follows: 


CALL ADJLPS (ibuf,iadj,[isb] ) 


ibuf 


An integer array that was previously specified in a synchronous 
input or output function. 


iadj 


The adjustment to be applied to the buffer pointers. For an 
input function, this specifies the number of data values that 
have been removed from the data buffer. For an output function, 
this specifies the number of data values that have been put into 
the data buffer. 


isb 
A 2-word integer array to which the subroutine status is 


returned. 


The isb array has the standard meaning described in Section 16.4.1. 


16.4.6 ASLSLN: Assigning a LUN to LSO: 


The ASLSLN FORTRAN subroutine assigns a logical unit number (LUN) to 
the LPS11. It must be called prior to executing any other Laboratory 
Peripheral Systems FORTRAN function or subroutine. Subsequent calls 
to other interface routines then implicitly reference the LPS11 with 
the LUN assigned. 


16-13 


LABORATORY PERIPHERAL SYSTEMS DRIVERS 


The call is issued as follows: 


CALL ASLSLN (lun,[isb],[iun]) 


lun 
The number of the LUN to be assigned to LSO: 

isb 
A 2-word integer array to which the subroutine status is 
returned. 

iun 


The unit number of the device to be assigned (defaults to 0 if 
not specified). 


The isb array has the standard meaning described in Section 16.4.1. 


16.4.7  ASARLN: Assigning a LUN to ARO: 


The ASARLN FORTRAN subroutine assigns a logical unit number (LUN) to 
the ARI11l. Tt must be called prior to executing any other laboratory 
peripheral system FORTRAN function or subroutine. Subsequent calls to 
other interface routines then implicitly reference the AR11 with the 
LUN assigned. 


The call is issued as follows: 


CALL ASARLN (lun,[isb],[iun] ) 


lun 
The number of the LUN to be assigned to ARO:. 

isb 
A 2-word integer array to which the subroutine status is 
returned. 

iun 


The unit number of the device to be assigned (defaults to 0 if 
not specified). 


The isb array has the standard meaning described in Section 16.4.1. 
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16.4.8 CVSWG: Converting a Switch Gain A/D Value to Floating-Point 


The CVSWG FORTRAN subroutine converts an A/D value from a synchronous 
A/D sampling function to a floating-point number. Each data item 
returned by a laboratory peripheral system driver consists of a gain 
code and converted value packed in a single word (see Section 
16.3.3.1). This form is not readily usable by FORTRAN, but is much 
more efficient than converting each value to floating point in the 
driver. This routine unpacks the gain code and value, and_ then 
converts the result to a floating-point number. It can be 
conveniently used in conjunction with the IRDB routine (see Section 
16.45.03) % 


The call is issued as follows: 


CVSWG (ival) 


ival 
The value to be converted to floating point. Its format must be 
that returned by a synchronous A/D sampling function. The 
conversion is performed according to the following formula: 
var = (64 * converted value)/conversion gain 
For the various gain codes, 


var = x * converted value 


as shown below: 


Gain x 
1 64 
4 16 
16 4 
64 1 


16.4.9 DRS: Initiating Synchronous Digital Input Sampling 


The DRS FORTRAN subroutine reads data qualified by a mask word from 
the digital input register at precisely timed intervals. Sampling may 
be started or stopped as for RTS (see Section 16.4.18) and all input 
is double buffered with respect to the user task. Data may be 
sequentially retrieved from the data buffer by the IRDB routine (see 
Section 16.4.12), or the ADJLPS routine (see Section 16.4.5) may be 
used in conjunction with direct access to the input data. The call is 
issued as follows: 


CALL DRS (ibuf,ilen,imode,irate,iefn,imask,isb,[nbuf], 
[istart],[istop]) 
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ibuf 
An integer array that is to receive the input data values. 
ilen 
The length of ibuf (must be even and greater than or equal to 6). 
imode 
The start, stop, and sampling mode. Its value is encoded by 
adding together the appropriate function selection values shown 
below. 
Function 
Selection 
Value Meaning 
128 Start on digital input point set 
64 Set digital output point at start 
32 Stop on digital input point clear 
16 Stop on number of buffers 
Thus, a value of 192 for imode specifies: 
e The sampling is to be started when a specified digital input 
point is set. 
e A digital output point is to be set when sampling is started. 
e Sampling will be stopped by a program request. 
irate 
A 2-word integer array that specifies the time interval between 
digital input samples. The first word specifies the interval 
units as follows: 
irate(l) Unit 
1 Real-time clock ticks 
2 Milliseconds 
3 Seconds 
4 Minutes 
The second word specifies the interval magnitude as a 16-bit 
unsigned integer. 
iefn 


The number of the event flag that is to be set each time a half 
buffer of data has been collected. 
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imask 


The digital input points to be read. 


isb 
A 2-word integer array to which the subroutine status is 
returned. 

nbuf 
The number of buffers of data to be collected. It is needed only 
if a function selection value of 16 has been added into imode. 

istart 
The digital input pointer number to be used to trigger sampling, 
and/or the digital output point number to be set when sampling is 
started. It is needed only if a function selection value of 128 
or 64 has been added into imode. 

istop 


The digital input point number to be used to stop. sampling. rt 
is needed only if a function selection value of 32 has been added 
into imode. 


When sampling is in progress, the first word of the isb array is zero 
and the second word contains the number of data values currently in 
the buffer. 


16.4.10 HIST: Initiating Histogram Sampling (LPS11 only) 


The HIST FORTRAN subroutine measures the elapsed time between a series 
of events with Schmitt trigger l. 


Each time a sample is to be taken, a counter is incremented and 
Schmitt trigger 1 is tested. If it has fired, then the counter is 
written into the user buffer and the counter is reset to 0. Thus’ the 
data returned to the user is the number of sample intervals between 
Schmitt trigger firings. If the counter overflows before Schmitt 
trigger 1 fires, a 0 value is written into the user buffer. Sampling 
may be started and stopped as for RTS (see Section 16.4.18) and all 
input is double buffered with respect to the user task. The call is 
issued as follows: 


CALL HIST (ibuf,ilen,imode,irate,iefn,isb,[nbuf], 
[istart],[istop]) 


ibuf 


An integer array that is to receive the input data values. 
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ilen 


The length of ibuf (must be even and greater than or equal to 4). 


imode 


The start, stop, and sampling mode. Its value is encoded 
adding the appropriate function selection values shown below: 


Function 
Selection 
Value Meaning 
128 Start of digital input point set 
64 Set digital output point at start 
32 Stop on digital input point clear 
16 Stop on number of buffers 


irate 


by 


A 2-word integer array that specifies the time interval between 
samples. The first word specifies the interval units as follows: 


‘irate(l) Unit 
Ha Real-time clock ticks 
2 Milliseconds 
3 Seconds 
4 Minutes 


The second word specifies the interval magnitude as a 16-bit 


signed integer. 
iefn 
The number of the event flag that is to be set each time a 


buffer of data has been collected. 


isb 


A 2-word integer array to which the subroutine status 


returned. 
nbuf 


half 


is 


The number of buffers of data to be collected. It is needed only 


if a function selection value of 16 has been added into imode. 
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istart 
The digital input point number to be used to trigger sampling 
and/or the digital output point number to be set when sampling is 
Started. It is needed only if a function selection value of 128 
or 64 has been added into imode. 

istop 
The digital input point number to be used to stop sampling. It 
is needed only if a function selection value of 32 has been added 
into imode. 

The isb array has the standard meaning described in Section 16.4.1. 

When sampling is in progress, the first word of the isb array is 0 and 


the second word contains the number of data values currently in the 
buffer. 


16.4.11 IDIR: Reading Digital Input 

The IDIR FORTRAN subroutine or function reads the digital input 
register aS an unsigned binary integer, or as four binary-coded 
decimal (BCD) digits. In the latter case, the BCD digits are 
converted to a binary integer before the value is returned to the 
caller. The call is issued as follows: 


CALL IDIR (imode,[ival],[isb]) 


imode 
The mode in which the digital input register is to be read. If 
imode equals 0, then the digital input register is read as four 
BCD digits and converted to a binary integer. Otherwise, it is 
read as a 16-bit unsigned binary integer. 


ival 


A variable that receives the value read. 


isb 


A 2-word integer array to which the subroutine status is 
returned. 


The isb array has the standard meaning described in Section 16.4.1. 


When the function form of the call is used, the value of the function 
is the same as that returned in ival. 
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16.4.12 IDOR: Writing Digital Output 

The IDOR FORTRAN subroutine or function clears or sets bits in the 
digital output register. The caller provides a mask word and output 
mode. Bits in the digital output registers corresponding to the bits 
specified in the mask word are either set or cleared according to the 
specified mode. The call is issued as follows: 


CALL IDOR (imode,imask,[newval],[{isb] ) 


imode 
Whether the bits specified by imask are to be cleared or set in 
the digital output register. If imode equals 0, then the bits 
are to be cleared. Otherwise, they are to be set. 

imask 
The bits to be cleared or set in the digital output register. It 
may be conveniently specified as an octal constant. 

newval 
A variable that receives the updated (actual) value written into 
the digital output register. 

isb 
A 2-word integer array to which the subroutine status is 
returned. 

The isb array has the standard meaning described in Section 16.4.1. 


When the function form of the call is used, the value of the function 
is the same as that returned in newval. 


16.4.13 IRDB: Reading Data from an Input Buffer 


The IRDB FORTRAN subroutine or function retrieves data sequentially 
from a buffer that a laboratory peripheral system driver is 
synchronously filling. If no data is available when the call is 
executed, the contents of the next location in the data buffer are 
returned without updating the buffer pointers. The call is issued as 
follows: 


CALL IRDB (ibuf,[ival] ) 


16-20 


LABORATORY PERIPHERAL SYSTEMS DRIVERS 


ibuf 


An integer array that was previously specified in a synchronous 
input sampling request (that is, DRS, HIST, or RTS). 


ival 


A variable that receives the next value in the data buffer. 


When the function form of the call is used, the value of the function 
is the same as that returned in ival. 


16.4.14 LED: Displaying in LED Lights (LPS11 only) 


The LED FORTRAN subroutine displays a 16-bit signed binary integer in 
the LED lights. The number is displayed with a leading blank 
(positive number) or minus (negative number), followed by five 
non-zero-suppressed decimal digits that represent the magnitude of the 
number. LED digits are numbered right to left starting at 1 and 
continuing to <5. The number may be displayed with or without a 
decimal point. The call is issued as follows: 


CALL LED (ival,[idec],[isb]) 


ival 
The variable whose value is to be displayed. 

idec 
The position of the decimal point. A value of 1 to 5. specifies 
that a decimal point is to be displayed. All other values 
specify that no decimal point is to be displayed. 

isb 


A 2-word integer array to which the subroutine status is 
returned. 


The isb array has the standard meaning described in Section 16.4.1. 
For example, the following call: 
CALL LED (-55,2) 


would cause -0005.5 to be displayed in the LED lights. 
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16.4.15 LPSTP: Stopping an In-Progress Synchronous Function 


The LPSTP FORTRAN Subroutine selectively stops a single synchronous 
request. The call is issued as follows: 


CALL LPSTP (ibuf) 


ibuf 


An integer array that specifies a buffer that was previously 
specified in a synchronous initiation request. 


16.4.16 PUTD: Putting a Data Item into an Output Buffer 

The PUTD FORTRAN subroutine puts data sequentially into a buffer that 
a laboratory peripheral system driver is synchronously emptying. If 
no free space is available, no operation is performed. The call is 
issued as follows: 


CALL PUTD (ibuf,ival) 


ibuf 
An integer array which was previously specified in a synchronous 
output request (SDO or SDAC). 

ival 


A variable whose value is to be placed in the next free location 
in the data buffer. 


16.4.17 RELAY: Latching an Output Relay (LPS11 only) 


The RELAY FORTRAN subroutine opens or closes the LPS11_ relays. The 
call is issued as follows: 


CALL RELAY (irel,istate,[isb] ) 


irel 
Which relay is to be opened or closed (0 for relay one, 1 for 
relay two). 

istate 
Whether the relay is to be opened or closed. If istate equals 0, 
the relay is to be opened. Otherwise, it is to be closed. 

isb 


A 2-word integer array to which the subroutine status is 
returned. 


The isb array has the standard meaning described in Section 16.4.1. 
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16.4.18 RTS: Initiating Synchronous A/D Sampling 


The RTS FORTRAN subroutine reads one or more A/D channels at precisely 
timed intervals, with or without auto gain-ranging. The auto 
gain-ranging algorithm (LPS11 only) causes the channels to be sampled 
at the highest gain at which saturation does not occur. 


Sampling can be started when the interface subroutine is called or 
when a specified digital input point is set. A digital output point 
can optionally be set when sampling is started. Sampling can be 
terminated by a program request (sStop-in-progress request or kill 
I/O), the clearing of a digital input point, or the collection of a 
specified number of buffers of data. 


All input is double buffered with respect to the user task. Each time 
a half buffer of data has been collected, the user task is notified 
(by the setting of an event flag) that data is available to be 
processed while the driver fills the other half of the buffer. Data 
can be sequentially retrieved from the data buffer with the IRDB 
routine (see Section 16.4.12), or the ADJLPS routine (see Section 
16.4.5) can be used in conjunction with direct access to the input 
data. The call is issued as follows: 


CALL RTS (ibuf,ilen,imode,irate,iefn,ichan,nchan,isb, 
{nbuf],[istart],[{istop]) 


ibuf 

An integer array that is to receive the converted data values. 
ilen 

The length of ibuf (must be even and greater than or equal to 6). 
imode 


The start, stop, and sampling mode. Its value is encoded by 
adding together the appropriate function selection values as 
shown below: 


Function 

Selection 

Value Meaning 
128 Start on digital input point set 
64 Set digital output point at start 
32 Stop on digital input point clear 
16 Stop on number of buffers 

8 Auto gain-ranging (LPS11 only) 
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irate 


A 2-word integer array that specifies the time interval between 


A/D samples. The first word specifies the interval unit as 
follows: 
irate(l1) Unit 
1 Real-time clock ticks 
2 Milliseconds 
3 Seconds 
4 Minutes 


The second word specifies the interval magnitude as a 16-bit 
unsigned integer. 


iefn 
The number of the event flag that is to be set each time a half 
buffer of data has been collected. 

ichan 
The starting A/D channel of the block of channels to be sampled 
synchronously (must be between 0 and 63 for LPS11 and between 0 
and 15 for AR11). 

nchan 
The number of A/D channels to be sampled (must be between 1 and 
64 for LPS11 and between 1 and 16 for AR11). 

isb 
A 2-word integer array to which the subroutine status is 
returned. 

nbuf 
The number of buffers of data that are to be collected. It is 
needed only if a function selection value of 16 has been added 
into imode. 

istart 
The digital input point number to be used to trigger sampling 
and/or the digital output point number to be set when sampling is 
started. It is needed only if a function selection value of 128 
or 64 has been added into imode. Points are numbered from 0 to 
15, allowing a maximum of 16 points to be specified. 

istop 


The digital input point number to be used to stop. sampling. Ee 
is needed only if a function selection value of 32 has been added 
into imode. 
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The values listed for ichan and nchan above are the maximum allowable 
for each of the devices. In practice, they are constrained by the 
number of channels available as specified during SYSGEN. 


The isb parameter has the standard meaning described in Section 
16.4.1. 


When sampling is in progress, the first word of the isb array is 0 and 
the second word contains the number of data values currently in the 
buffer. 


16.4.19 SDAC: Initiating Synchronous D/A Output 


The SDAC FORTRAN subroutine writes data into one or more external D/A 
converters at precisely timed intervals. Output may be started and 
stopped as for RTS (see Section 16.4.18), and all input is double 
buffered with respect to the user task. One full buffer of data must 
be available when synchronous output is initiated. 


After SDAC has initiated output and the specified event flag has been 
set to notify the task that free buffer space is available, the PUTD 
routine (see Section 16.4.16) may be used to put data values 
sequentially into the output data buffer. The ADJLPS routine (see 
Section 16.4.5) may be used in conjunction with direct access to the 
output data buffer. The SDAC call is issued as follows: 
CALL SDAC (ibuf,ilen,imode,irate,iefn,ichan,nchan,isb, 
[nbuf],[istart],[istop]) 
ibuf 


An integer array that contains the output data values. 


ilen 


The length of ibuf (must be even and greater than or equal to 6). 


imode 


The start, stop, and sampling mode. Its value is encoded by 
adding together the appropriate function selection values as 
shown below: 


Function 

Selection 

Value Meaning 
128 Start on digital input point set 
64 Set digital output point at start 
22 Stop on digital input point clear 
16 Stop on number of buffers 
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irate 


A 2-word integer array that specifies the time interval between 


D/A outputs. The first word specifies the interval units as 
follows: 
irate(1) Unit 
1 Real-time clock ticks 
2 Milliseconds 
3 Seconds 
4 Minutes 


The second word specifies the interval magnitude as a 16-bit 
unsigned integer. 


iefn 
The number of the event flag that is to be set each time a half 
buffer of data has been output. 

ichan 
The starting D/A channel of the block of channels to be _ written 
into synchronously (must be between 0 and 9 for LPS11, and be 0 
or 1 for ARI1). 

nchan 
The number of D/A channels to be written into (must be between 1 
and 10 for LPS11, and be 1 or 2 for ARI11). 

isb 
A 2-word integer array to which the subroutine status is 
returned. 

nbuf 
The number of buffers of data to be output. It is needed only if 
a function selection value of 16 has been added into imode. 

istart 


The digital input point number to be used to trigger sampling 
and/or the digital output point number to be set when sampling is 
started. It is needed only if a function selection value of 128 
or 64 has been added into imode. Points are numbered from 0 to 
15, allowing a maximum of 16 points to be specified. 
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istop 


The digital input point number to be used to stop sampling. dig 
is needed only if a function selection value of 32 has been added 
into imode. 


The isb array has the standard meaning described in Section 16.4.1. 


When sampling is in progress, the first word of the isb array is 0 and 
the second word contains the number of free positions in the buffer. 


16.4.20 SDO: Initiating Synchronous Digital Output 


The SDO FORTRAN subroutine writes data qualified by a mask word into 
the digital output register at precisely timed intervals. Sampling 
may be started and stopped as for RTS (see Section 16.4.18) and all 
input is double buffered with respect to the user task. One full 
buffer of data must be available when output is initiated. 


After SDO has initiated output, and the specified event flag has been 
set to notify the task that free buffer space is available, the PUTD 
routine (see Section 16.4.16) may be used to put data values 
sequentially into the output data buffer. The ADJLPS routine (see 
Section 16.4.5) may be used in conjunction with direct access to the 
output data buffer. The SDO call is issued as follows: 


CALL SDO (ibuf,ilen,imode,irate,iefn,imask,isb,[nbuf], 
fistart],[istop] ) 


ibuf 

An integer array that contains the digital output values. 
ilen 

The length of ibuf (must be even and greater than or equal to 6). 
imode 


The start, stop, and sampling mode. Its value is encoded by 
adding together the appropriate function selection values as 
shown below: 


Function 
Selection 
Value Meaning 
128 Start on digital input point set 
64 Set digital output point at start 
32 Stop on digital input point clear 
16 Stop on number of buffers 
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irate 


A 2-word integer array that specifies the time interval between 
digital outputs. The first word specifies the interval units as 


follows: 
irate(l) Unit 
1 Real-time clock ticks 
2 Milliseconds 
3 Seconds 
4 Minutes 


The second word specifies the interval magnitude as a 16-bit 
unsigned integer. 


iefn 
The number of the event flag that is to be set each time a half 
buffer of data has been output. 

imask 
The digital output points that are to be written. It may be 
conveniently specified as an octal constant. 

isb 
A 2-word integer array to which the subroutine status is 
returned. 

nbuf 
The number of buffers of data to be output. It is needed only if 
a function selection value of 16 has been added into imode. 

istart 
The digital input point number to be used to trigger sampling 
and/or the digital output point number to be set when sampling is 
started. It is needed only if a function selection value of 128 
or 64 has been added into imode. Points are numbered 0 through 
15, allowing a maximum of 16 points to be specified. 

istop 


The digital input point number to be used to stop sampling. It 
is needed if a function selection value of 32 has been added into 
imode. 


The isb parameter has the standard meaning described in Section 
16.4.1. 


When Sampling is in progress, the first word of the isb array is 0 and 
the second word contains the number of free positions in the buffer. 
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16.5 STATUS RETURNS 


The error and status conditions listed in Table 16-8 are returned by 
the Laboratory Peripheral System drivers described in this chapter. 


Table 16-8 
Laboratory Peripheral Systems Status Returns 


IS.SUC 


Successful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the 
I/O status block can be examined to determine the 
number of data values processed. 


IS. PND I/O request pending 


The operation specified in the QIO directive has 
not yet been completed. 


IE.ABO Operation aborted 


The specified I/O operation was canceled (by 
IO.KIL or IO.STP) while in progress. 


IE.BAD Bad parameter 


An illegal specification was supplied for one or 
more of the device-dependent QIO parameters (words 
6-11). The second I/O status word is filled with 


Byte alignment was specified for a data buffer but 
only word alignment is legal for Laboratory 
Peripheral Systems. Alternatively, the length of 
a buffer is not an even number of bytes. 


IE.DAO Data overrun 


For Laboratory Peripheral Systems, the driver 
attempted to get a value from the user buffer when 
none waS available or attempted to put a value in 
the user buffer when no space was available. 


IE.DNR Device not ready 


The physical device. unit specified in the QIO 
directive was not ready to perform the desired I/0 
operation. For Laboratory Peripheral Systems, 
this code is returned if a device time-out occurs 
while a function is in progress. The second I/0 
Status word contains the number of free positions 


| | in the buffer, as appropriate. | 


(continued on next page) 


Os. 
TE. BYT Byte-aligned buffer specified 
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Table 16-8 (Cont.) 
Laboratory Peripheral Systems Status Returns 


IE. IEF Invalid event flag number 


| An invalid event flag number was specified in a 
synchronous function. 
IE.IFC Tllegal function 
A function code was included in an I/O request 
that is illegal for the LPS11l or ARI1. 


IE.NOD Insufficient buffer space 


Dynamic storage space has been depleted, and there 
is insufficient buffer space available to allocate 
a secondary control block for a synchronous 
function. 


IE.OFL Device off line 


The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not 
in the configuration. 


IE.ONP Option not present 


An option dependent function or subfunction was 
requested, and the required feature was not 
specified at system generation. For example the 
gain-ranging option or D/A option is not present. 
The second I/O status word contains 0. 


IE.PRI Privilege violation 
The task which issued the request was not 
privileged to execute that request. For 
Laboratory Peripheral Systems, a checkpointable 
task attempted to execute a synchronous sampling 
function. 


IE.RSU Resource in use 


A resource needed by the function requested in the 
QIO directive was being used (see Section 16.5.1). 


IE.SPC Illegal address space 


The buffer specified for a read or write request 
was partially or totally outside the address space 
of the issuing task. Alternately a byte count of 
0 was specified. The second I/O status word 
contains 0. 


FORTRAN interface values for these status returns are presented in 
Section 16.5.4. 
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16.5.1 IE.RSU 


IE.RSU is returned if a function requests a resource that is currently 
being used. The requesting task may repeat the request at a later 
time or take any alternative action required. 


Because certain functions do not need such resources, they never cause 
this code to be returned. Other functions return this code under the 
following conditions: 


Function When IE.RSU Is Returned 
I0.SDO One or more specified digital output bits are in 
use. 
IO.ADS Digital output point (if specified) is in use. 
IO.HIS Digital output point (if specified) is in use. 
IO.MDA Digital output point (if specified) is in use. 
IO0.MDI Digital output point (if specified) or digital 


input points to be sampled are in use. 


TO.MDO Digital output point (if specified) or output bits 
to be written are in use. 


The following components of the Laboratory Peripheral Systems are each 
considered a Single resource: 


Resource When Shareable 

The A/D Converter Always shareable 

and clock 

Each bit in the Never shareable. 

digital output 

register 

Each bit in the Always shareable when used by I0.SDI 

digital input or for start/stop conditions (specified 

register in subfunction modifier bits), even when 
in use by another’ function; when 


specified by a synchronous digital input 
function, not shareable with another 
such function 


Each resource is allocated on a first-come-first-served basis. (That 


is, when a conflict arises, the most recent request is rejected with a 
status of IE.RSU). 


16.5.2 Second I/O Status Word 


On successful completion of a function specified in a QIO macro call, 
the IS.SUC code is returned to the first word of the I/O status block. 


Table 16-9 lists the contents of the second word of the status block 


ei olo Me be Sse we eV asks 


on successful completion for each function. 
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Table 16-9 
Returns to Second Word of I/O Status Block 


Successful 
Function Contents of Second Word 
IO.KIL Number of data values before I/0 was canceled 
IO. LED 0 
IO.REL 0 
I0.SDI Masked value read from digital input register 
I0.SDO Updated value written into digital output register 
IO.ADS Number of data values remaining in buffer 
I0O.HIS Number of data values remaining in buffer 


IO.MDA Number of free positions in buffer 


IO.MDI Number of data values remaining in buffer 


IO.MDO Number of free positions in buffer 


IO.STP 0 


When IE.BAD is returned, the second I/O status word contains 0/ 
Laboratory Peripheral Systems drivers return the IE.BAD code under the 
following conditions: 


Function When IE.BAD is Returned 
IO. REL Relay number not 0 or 1 
IO.ADS No I/O status block, illegal digital I/0 point 
IO.MDA number, or illegal channel number 
IO.HIS No I/O status block or illegal 
IO.MDI digital I/O point number 
IO0.MDO 


16.5.3 I0.ADS and ADC Errors 


While IO.ADS or the ADC FORTRAN subroutine is converting a sample, two 
error conditions may arise. Both of these conditions are reported to 
the user by placing illegal values in the data buffer. A -1 
(177777(8) is placed in the buffer if an A/D conversion does not 
complete within 30 microseconds. A ~-2 (177776(8) is placed in the 
buffer if an error occurs during an A/D conversion (LPS11i only). 
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16.5.4 FORTRAN Interface Values 


The values listed in Table 16-10 are returned in FORTRAN subroutine 
calls. 


Table 16-10 
FORTRAN Interface Values 


Status Return FORTRAN Value 


IS.SUC 

IS. PND 

IE.ABO 

IE.ADP +101 

IE.ALN | +334 
| 


+00 
+315 


IE.BAD +301 
IE.BYT +319 
IE.DAO 
IE.DNR 
LE. TSF 
IE.IFC 
IE. ILU 
IE.NOD 
IE.OFL 
IE.ONP 
IE.PRI 
IE.RSU 
IE.SDP 
IE.SPC 
IE.ULN 
IE.UPN 


16.6 PROGRAMMING HINTS 


This section contains information on important programming 
considerations relevant to users of the Laboratory Peripheral Systems 
drivers described in this chapter. 


16.6.1 The LPS11/AR11 Clock and Sampling Rates 


The basic real-time clock frequency (count rate) for all synchronous 
functions is always 10KHz. Device characteristics word 4 contains a 
16-bit buffer preset value -- set dynamically or at system generation, 
that controls the rate of "ticks" (that is, the rate at which the 
clock interrupts). The quotient that results when this value is 
divided into 10KHz is the rate of "ticks." For example, if this value 
is 2, the "tick" rate is 5KHz. The user can use a Get LUN Information 
system directive to examine the value and a SET /BUF MCR function to 
modify it while the system is running. 
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The ticks parameter in a synchronous function specifies the number of 
"ticks" between samples or data transfers. The value of ticks is a 
16-bit number. Thus 65,536 discrete sampling frequencies are possible 
for each of 65,536 different "tick" rates. This provides a maximum 
Single-channel sample rate of 1 sample every 100 microseconds 
(possible in hardware but impractical in software) and a minimum of 1 
sample every 429,495 seconds. A single-channel rate greater than 2KHz 
is possible, but not recommended. 

The figures below represent initial timing tests run under RSX-11M. 
It should be noted that no computation was performed on the data other 
than continuously removing it from or inserting it into the data 
buffer. 


The following data is for the LPS11 on a PDP-11/40 with memory 
management, with no gain-ranging option, and with digital I/O option. 


Analog rates: 
1 request for 1 channel at 2.5KHz 
1 request for 2 channels at 2.0KHz (aggregate 4KHz) 
2 requests for 1 channel at 2.0KHz (aggregate 4KHz) 
Digital rates: 
1 request for 2 channels at 2.5KHz (aggregate 5KHz) 


The following data is for the AR11 on a PDP-11/40 with no memory 
management, no digital I/O option, and no unipolar sampling. 


Analog rates: 
1 request for 1 channel at 3.3KHz 
1 request for 2 channels at 2.5KHz (aggregate 5.0KHz) 
2 requests for 1 channel at 2.5KHz (aggregate 5.0KHZz) 
Digital rate: 


2 requests for 2 channels at 3.3KHz (aggregate 6.6KHz) 


16.6.2 Importance of the I/O Status Block 


An I/O status block must be specified with every synchronous function. 
If the first I/O status word is nonzero, the request has been 
terminated and the value indicates the reason for termination. 
Otherwise, the request is in progress, and the second I/O status word 
contains the number of data values remaining in the buffer (or the 
number of free positions in the buffer for IO.MDA and IO.MDO). 
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16.6.3 Buffer Management 


The buffer unload protocol for synchronous input functions is 
described below. The user constructs a 5-word block that contains the 
following: 


IOSB: .- BLKW 2 ; I/O STATUS DOUBLE-WORD 
CURPT: -WORD BUFFER ; ADDRESS OF BUFFER 

LSTPT: - WORD BUFFER+n ; ADDRESS OF END OF BUFFER 
FSTPT: -WORD BUFFER ; ADDRESS OF BUFFER 


Two of these words are required by the driver (I/O status block) and 
the remaining three by the user to unload data values from the buffer. 


The user then issues the I/O request with the appropriate parameters 
and the address of the above block as the I/O status block. The QIO 
directive 0s both I/O status words to initialize them. 


If the driver accepts the request, it sets up a write pointer to the 
first word in the user buffer. Thus, the user has a buffer read 
pointer and the driver has a buffer write pointer. The user and_ the 
driver share the second I/O status word, which is the number of data 
words in the buffer that contain data. 


Each time the driver attempts to put a sample value into the buffer, 
it increments the second I/O status word and compares the result with 
the size of the buffer. If the result is greater, buffer overrun has 
occurred and the request is terminated. Otherwise, the value is 
stored in the buffer at the address specified by the driver's write 
pointer and the write pointer is updated. 


If the value stored in the user buffer fills half of the buffer, the 
event flag specified in the I/O request is set in order to notify the 
user that a half buffer of data is available to be processed. Each 
time the user task is awakened, it should execute the following code: 


55: CLEFSS #EFN ;CLEAR EFN 
10S: TST IOSB+2 ;ANY DATA IN BUFFER? 
BEQ 30$ ;1F EQ NO 
MOV @CURPT,RO ;GET NEXT VALUE FROM BUFFER 
DEC IOSB+2 ;REDUCE NUMBER OF ENTRIES 
ADD #2,CURPT ;UPDATE BUFFER READ POINTER 
CMP CURPT,LSTPT sEND OF BUFFER? 
BLOS 208 ;IF LOS NO 
MOV FSTPT,CURPT ;RESET BUFFER READ POINTER 
20S: Process data value : 
BR 10s *TRY AGAIN 
30S: TSTB IOSB ;REQUEST TERMINATED? 
BNE 40$ ;IF NE YES 
WTSESS #EFN ;WAIT FOR EFN 
BR 5S 48 
40S: Determine reason for termination 
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For IO.MDA and IO.MDO, this protocol differs slightly. The user’ task 
maintains a write pointer and the driver a read pointer. The entire 
buffer must be full when the request is executed. 


The following FORTRAN example illustrates the proper protocol for 
using ADJLPS for synchronous input and output. 


Synchronous input: 


DIMENSION IBF(1004),IERR(2) , INTVL(2) 


C 
C INITIATE SYNCHRONOUS A/D SAMPLING, 
C 
INTVL (1) =2 
INTVL (2) =5 
CALL RTS(IBF,1004,160,INTVL, IEFN,6,6,IERR,50,14,15) 
Cc 
C INITIALIZE HALF BUFFER INDEX 
C 
INDX=4 
Cc 
C WAIT FOR HALF BUFFER OF DATA 
c 
10 CALL WAITFR(IEFN) 
Cc 
C CLEAR EVENT FLAG 
C 
15 CALL CLREF(IEFN) 
c 
C PROCESS HALF BUFFER OF DATA 
C 


SUM=0 

DO 20 I=1,500 

SUM=SUM+CVSWG (IBF (I+INDX) ) 
20 CONTINUE 

AVERG=SUM/500 


FREE HALF BUFFER FOR MORE DATA 


aaa 


CALL ADJLPS (IBF,500) 


ADJUST BUFFER INDEX 


aan 


INDX=INDX+500 
IF(INDX.GE.1004) INDX=4 


CHECK IF ANOTHER HALF BUFFER OF DATA IS AVAILABLE 


aAaAN 


IF(IERR(2).GE.500 GO TO 15 
IF(IERR(1).NE.0) GO TO end of sampling 
GO TO 10 
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Synchronous output: 


AAQAAAANAN 


ana 


QaaAND 


10 


DIMENSION IBF(1004),IERR(2) ,INTVL (2) 


FIRST BUFFER OF DATA MUST BE AVAILABLE AT START 
THIS EXAMPLE ASSUMES FIRST BUFFER IS FULL AT START 


START SYNCHRONOUS DIGITAL OUTPUT FUNCTION 


INTVL (1) =2 
INTVL(2)=5 
CALL SDO(IBF,1004,160,INTVL, IEFN,MASK, IERR,50,14,15) 


INITIALIZE HALF BUFFER INDEX 


INDX=4 


WAITFOR ROOM IN BUFFER 


CALL WAITFR(IEFN) 


C 
C CLEAR EVENT FLAG 
€ 


CALL CLREF(IEFN) 


C CALCULATE VALUES TO PUT IN BUFFER 


C 


20 


aQAaaAA aan 


aQaaANn 


X= (Y+2) *Z 

DO 20 I=1,500 

IBF (I+INDX) =X**5/A 
CONTINUE 


SIGNIFY ANOTHER HALF BUFFER IS FULL 


CALL ADJLPS (IBF,500) 


ADJUST BUFFER INDEX 


INDX=INDX+500 
IF(INDX.GE.1004) INDX=4 


CHECK IF ANOTHER HALF BUFFER IS EMPTY 


IF(IERR(2).GE.500) GO TO 15 
IF(IERR(1).NE.0) GO TO end of sampling 
GO TO 10 


NOTE 


In both of the examples above, care is taken to ensure 
that the program stay "in sync" with the driver. If the 
program "loses" its position with respect to the driver, 
the function must be stopped and restarted, Since this is 
the only way to recover. Caution should be exercised _ to 
ensure that the program sequence above be used to avoid a 
possible loss of data. 
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QIO DPB format: 


QIOSC IO.SAO,...,<chn,vout> 


chn 


The output channel number. 


vout 

The output voltage representation. 
Output voltage varies linearly with the binary input to the channel, 
where 0 to plus 10 volts (+10v.) is represented by integers from 0 to 
1023. 
Return Status: 

IS.SUC - Function submitted for output to controller. 


IE.MOD - Nonexistent D/A channel was specified. 


The second I/O status word is 0. 


18.3.4 Momentary Digital Output - Multi-Point 

This function provides the capability of pulsing a field of up to 16 
momentary (Single-shot) digital output points. Fields must be aligned 
on module boundaries. 


QIO DPB format: 


QTO$C IO.MSO,...,<opn,dp> 


opn 


The starting digital output point number. Point number must be 
aligned on a module boundary (that is, must be a multiple of 16). 


dp 
The 16-bit mask. One point is pulsed corresponding to each bit 
set in the mask word. 

Return Status: 
IS.SUC - Function submitted for output to the controller. 


TE.MOD -— Invalid starting point number’ specified. Point is 
nonexistent or not aligned on a module boundary. 


CHAPTER 17 


PAPER TAPE READER/PUNCH DRIVERS 


17.1 INTRODUCTION 


The RSX-11M/M-PLUS paper tape reader/punch drivers support the PCll 
paper tape reader/punch and the PR11l paper tape reader. The PCll is a 
high-speed reader/punch capable of reading 8-hole, unoiled, perforated 
paper tape at 300 characters per second, and punching tape at 50 
characters per second. The PR11 has the same characteristics as those 
of the paper tape reader portion of the PCll. All transfers are image 
mode only, with no interpretation of data. 


17.2 GET LUN INFORMATION MACRO 


Word 2 of the buffer filled by the GET LUN INFORMATION system 
directive (the first characteristics word) contains the following 
information for paper tape devices. A bit setting of 1 indicates that 
the described characteristic is true for these devices. 


Bit Setting Meaning 
0 i Record-oriented device 
1 0 Carriage-control device 
2 0 Terminal device 
3 0 File-structured device 
4 0 Single-directory device 
5 0 Sequential device 
6 0 Mass storage device 
7 0 User-mode diagnostics supported 
8 0 Device supports 22-bit direct addressing 
9 0 Unit software write-locked 
10 0 Input spooled device 
ii 0 Output spooled device 
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Bit Setting Meaning 

12 0 Pseudo device 

13 0 Device mountable as a communications channel 
14 0 Device mountable as a FILES-11 volume 

15 0 Device mountable 


Words 3 and 4 of the buffer are undefined; word 5 indicates’ the 
default buffer size, which is 64 bytes for paper tape devices. 


17.3 QIO MACRO 
Table 17-1 lists the standard functions of the QIO macro that are 
valid for the paper tape reader/punch. 


Table 17-1 
Standard QIO Functions for the Paper Tape Reader/Punch 


IO.ATT,... 


Attach device 


Detach device 


LOVDET 5:5 676 


LO. KI EG je Cancel I/O requests 


IO.RLB,...,<stadd,size> READ logical block (reader 


READ virtual block (reader 


IO.RVB,...,<Stadd,size> 


IO.WLB,...,<Stadd,size> WRITE logical block (punch 


IO.WVB,...,<stadd,size> WRITE virtual block (punch 


stadd 
The starting address of the data buffer (may be on a byte 
boundary) 

size 
The data buffer size in bytes (must be greater than 0) 

IO.KIL never cancels an in-progress read request. In-progress write 


requests are canceled only when the punch driver is waiting for the 
punch to become ready at the start of a transfer. 


The paper tape drivers support no device-specific functions. 
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17.4 STATUS RETURNS 


Table 17-2 lists error and status conditions that are returned by 


paper tape reader/punch drivers. 


Is.Suc 


IS. PND 


ITE.ABO 


| ITE.DAA 
IE.DNA 
IE.DNR 


IE.EOF 


Table 17-2 
Paper Tape Reader/Punch Status Returns 


Successful completion 


The operation specified in the QIO directive was 
completed successfully. The second word of the I/0 
status block can be examined to determine the number 
of bytes processed, if the operation involved reading 
or writing. 


I/O request pending 


The operation specified in the QIO directive has not 
yet been executed. The I/O status block is filled 
with Os. 


Operation aborted 


The I/O request was cancelled while in progress or 
while still in the I/O queue. 


Device already attached 


The physical device unit specified in an I0O.ATT 
function was already attached by the issuing task. 
This code indicates that the issuing task has already 
attached the desired physical device unit, not that 
the unit was attached by another task. 


Device not attached 


The physical device unit specified in an I0.DET 
function was not attached by the issuing task. This 
code has no bearing on the attachment status of other 
tasks. 


Device not ready 


The reader and punch drivers return this code when a 
time-out occurs. The reader driver also returns this 
code when an error condition (see Section 17.4.1) is 
encountered before the initiation of the first 
transfer after an ATTACH command has been issued. 


End-of-file encountered 


The reader driver encountered an error condition (see 
Section 17.4.1) at a time other than the initiation 
of tne first read after a vaiid ATTACH command. The 
second word of the I/O status buffer contains a count 
of bytes successfully read before the error condition 


was encountered. 


(continued on next page) 
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Table 17-2 (Cont.) 
Paper Tape Reader/Punch Status Returns 


pce | eason 


IE.IFC Illegal function 
An illegal function code was specified in an I/O 
request that is not legal for the respective paper 
tape drivers. 

IE.OFL Device off line 
The physical device unit associated with the LUN 
specified in the QIO directive was not on line. When 
the system was booted, a device check indicated that 
this physical device unit was not in the 
configuration. 

IE.SPC Illegal address space 
The buffer specified for a read or write request was 
partially or totally outside the address space of the 
issuing task. Alternatively, a byte count of 0 was 
specified. 

IE.VER Unrecoverable hardware error (punch only) 
The punch driver encountered an error condition (see 
Section 17.4.1) at a time other than the initiation 
of a transfer. Section 17.4.2 describes the action 


of the punch driver when an error condition is 
encountered upon the initiation of a transfer. 


17.4.1 Error Conditions 


There are four error conditions that are indistinguishable to the 
paper tape drivers. These conditions are: 


e No tape 
e Reader off line 
e@e Power low 


e@e Hardware malfunction 


17.4.2 Ready Recovery 


When the punch driver encounters an error condition upon the 
initiation of a transfer, the following message is displayed: 


*** PPn: -- NOT READY 


The unit number of the paper tape punch that is not ready. 
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This message is repeated every 15 seconds until the error condition is 
corrected, or until the I/O request is canceled. When the error 
condition has been corrected, the transfer will begin within 1 second. 


17.5 PROGRAMMING HINTS 


This section contains information on important programming 
conSiderations relevant to users of the paper tape drivers described 
in this chapter. 


17.5.1 Special Action Resulting from Attach and Detach 


When an Attach or Detach is issued to the punch, the punch driver 
initiates a transfer of 170 (decimal) nulls. Upon the first read 
after an attach to the reader, all nulls preceding the first non-null 
character on the tape are read and discarded by the reader driver. 


17.5.2 Reading Past End-of-Tape 


When the reader driver reads past the physical end-of-tape, it 
normally generates at least two incorrect data bytes. These bytes are 
included in the byte count returned by the driver. User software that 
does not prevent reads past the physical end-of-tape should discard at 
least the last six characters in the buffer when IE.EOF is returned by 
the driver. 
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18.3.5 Bistable Digital Output - Multi-Point 

This function provides the capability of setting or resetting a field 
of up to 16 bistable digital output points. Fields must be aligned on 
a module boundary. 


QIO DPB format: 


OFOSC -TO.MLO, «-«. ¢<OPN ,Pp7dp> 


opn 
The starting digital output point number. Point number must be 
aligned on a module boundary (that is, must be a multiple of 16). 
Pp 
The 16-bit mask. 
dp 


The data pattern. 
A bit is set in the mask word for each point that may change state. 
The state of points corresponding to reset mask bits is unaltered. 
When the mask bit is set, the output is "closed" if the data bit is 
set and "open" if the data bit is clear. 
Return Status: 


IS.SuC - Function submitted for output to the controller. 


IE.MOD - Invalid starting point number specified. Point does not 
exist or is not aligned on a module boundary. 


18.3.6 Unsolicited Interrupt Processing 
Unsolicited interrupts consist of the following: 
1. Digital interrupts 
2. Counter interrupts 
3. Remote terminal input 
4. Hardware errors 


Based on the type of interrupt, the driver may dispose of the 
interrupt data in one or more of the following ways: 


1. The data may be furnished to a task that has issued a request 
to monitor such information continually. This alternative is 
not available in the DSS/DRS driver. 


2. A task may be activated by a specific input. That is, a 


dormant task can be requested to run, or an event flag may be 
set if the task is currently active. 


Low Ly 
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18.1 INTRODUCTION 


This chapter describes RSX-11M drivers for two process I/O subsystems: 
the ICS/ICR11 and the DSS/DRS11. (Driver support for these I/0 
subsystems is not provided in RSX-11M-PLUS systems.) 


ICS11 and ICR11 are local and remote process I/0 subsystems, 
respectively. They operate under program control as devices capable 
of interrogating digital and analog input, and driving digital and 
analog output. 


DSS11 and DRS11 are digital input and output subsystems, respectively. 


Under program control they drive digital output and interrogate 
digital input. . 


18.1.1 Hardware Configuration 


A single ICS or ICR controller can handle up to 16 I/O modules in any 


configuration; a module contains 16 bits of input or output data, 
providing a total of 256 digital points. Up to 12 ICR or ICS units 
are supported. The ICS/ICR driver is tailored to the user's needs, 


interactively, through the SYSGEN (System Generation program) 
dialogue. The driver is capable of handling any combination of ICR or 
ICS controllers installed on a single system. 


The DSS11 provides 49 optically isolated inputs, including 48 
nonbuffered, sense-data inputs and one interrupt input. The DRS11 
provides 48 open-collector, buffered outputs plus one interrupt input. 
The DSS/DRS driver is shaped to the user's system configuration in the 
SYSGEN dialog. The driver supports up to 16 DSS11 and/or DRS11 
modules. 


18.1.1.1 ICS/ICR Address Assignments - Each ICR11A Unibus’ interface 
or ICS11 file box must be configured at SYSGEN time for individually 
addressable interrupt vectors, Control and Status Registers (ICSR), 
and module Address Registers (ICAR), as shown in Table 18-1. 
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18.1.1.2 


DSS/DRS 


However, 
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ICS/ICR Address Assignments 


ICS/ICR Unit No. Module Addresses ICSR/ICAR Addresses | Interrupt Vectors 


171000-171036 
171040-171076 
171100-171136 
171140-171176 
171200-171236 
171240-171276 
171300-171336 
171340-171376 
171400-171436 
171440-171476 
171500-171536 


171540-171576 


Table 18-1 


171770-171776 
171760-171766 
171750-171756 
171740-171746 
171730-171736 
L717 20=171:726 
171710-171716 
171700-171706 
171670-171676 
171660-171666 
171650-171656 


171640-171646 


234-236 
XXX-XXX+2 
XXX+4-xxx+6 
XXX+10-xxx+12 
XxXX+14-xxx+16 
XXX+20-xXxXx+22 
XXX+24-xXxXxX+26 
XXX+30-xXxXx+32 
XXX+34-xxx+36 
XXX+40-xxxt+42 
XXX+44-xxx+46 


XXX4+50-xxx+52 


NOTES 


nnnnn6 Control and Status Register 
nnnnn4 = Address Register 


Additional controllers are 
addresses above 300. 


assigned vector 


DSS/DRS Address Assignments - Unlike the ICS/ICR 
devices are not restricted to specified bus 
the following constraints apply: 


subsystem, 
addresses. 


All DSS11 modules must occupy a contiguous set of bus 
addresses. 

All DRS11 modules must occupy a contiguous set of bus 
addresses. 

The total number of DSS11 and DRS11 modules may not exceed 
16% 

If both module types are installed in a system, the DRS11 


must occupy the lower set of bus and 


interrupt-vector 
addresses. 


Bus request priority is BR4. 
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18.1.1.3 Supported ICS/ICR I/O Modules - The following modules, all 
optional, are supported by the ICS/ICR driver: 
D/A Converters 

IDA-OA - 4-channel digital-to-analog converter 
A/D Converters 

IAD-IA - 8-channel wide-range differential analog-to-digital 

converter 

IMX-IA - 16-channel flying capacitor relay multiplexer 
Counters 

IDC-IC - 16-bit binary counter 
Bistable Digital Outputs 

IDC-OA - D/C flip-flop driver 

IAC-OA - A/C flip-flop driver 


IRL-OA - Bistable relay output 
IRL-OB Flip-flop relay output 


Momentary Digital Output 


IDC-OB - D/C momentary driver 
IAC-OB - A/C momentary driver 


Digital Inputs (Noninterrupting) 4 
IDC-IA - D/C voltage sense input 
IDC-ID - D/C voltage input module 
IAC-IA - A/C voltage input module 

Digital Inputs (Interrupting) 


IDC-IB - D/C voltage interrupt input 
IAC-IB - A/C voltage interrupt input 


Terminal Input/Output 


110 CPS Remote Terminal Interface to ICR11 


18.1.2 Alternate ICS11 Support 


The ICS11 Industrial Control Subsystem is supported either by the 
UDCl1l or ICS/ICR11 device driver. If the system does not have an 
ICR11 controller, and if a driver of minimum size is required, then 
UDC1ll support should be considered. The hardware requirements for 
such Support are as follows: 


1. Each file box must be assigned to the same interrupt vector 
address (normally 234). 


2. The control and status register within each file box must 


appear at the same address within the I/O page (normally 
171776) 
tin tive 


1. Note that noninterrupting input modules are accessed directly by a 
task. Hence, while FORTRAN interface routines are available, no 
support for such modules is included in the driver. 
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If support of the IAD-IA A/D converter is required, the following 
module addressing and installation conventions are imposed: 


1. Each IAD-IA converter and associated IMX-IA relay 
multiplexers are assigned a fixed block of 120 logical 
channel numbers. No more than 32 IAD-IA converters may be 
installed in a single system. Based on this convention, A/D 
converter 0 occupies channels 0-119, A/D converter 1 occupies 
120-239, and so forth. 


2. Regardless of the actual number of IMX-IA multiplexers 
installed, each converter preempts a block of eight 
contiguous module slots. 


3. The slots reserved for all A/D converters and multiplexers 
must occupy a block of contiguous module slots. 


If necessary, Field Service personnel can make the vector and address 
changes. Assuming the hardware configuration is correct, the user can 
implement the desired UDCl1l software support by answering in the 
affirmative all SYSGEN questions relating to the UDCll. 


If the additional ICS/ICR-1l driver features are required (at a 
commensurate increase in the memory requirements), then each ICS11 
file box must be configured for individually addressable interrupt 
vectors and control status registers. This change can be performed by 
Field Service personnel. The necessary software support is 
incorporated by answering in the affirmative all SYSGEN questions 
relating to the ICS/ICRI11. 


The additional ICS11 capabilities provided by the ICS/ICR11 driver may 
be summarized as follows: 


1. Multicontroller, parallel operation 
2. Increased A/D conversion throughput 


3. Activation of tasks directly from digital interrupts or 
counters 


4, No requirement to install modules of the same type in 
contiguous slots 


Section 18.7 summarizes the software differences between the UDC and 
ICS/ICR drivers in detail. 


18.1.3 Software Support 
Both ICS/ICR and DSS/DRS operations are divided into two categories: 
1. Functions performed directly by any task 
2. Functions requiring driver services 
Direct functions are accomplished through memory references to. the 
ICS/ICR or DSS/DRS registers on the I/O page. In a protected system 
any task may gain restricted access to the device registers by linking 
to a global common block that resides within the appropriate physical 
memory limits. Direct functions consist of: 


1. Reading counter modules 


2. Reading any digital input module (DSS) 
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NOTE 
All functions listed in this subsection 
apply to ICS/ICR modules. Those which 
also apply to the DSS and/or DRS 
subsystems are so marked. 
Driver requests are divided into the following categories: 
1. Noninterrupting output functions 
a. Bistable igieeseicpy Siwiees output (DRS) 
b. Analog output 
c. Momentary (single-shot) digital output 
2. Requests for interrupting functions 
a. Analog input 
b. Remote terminal output 
3. Requests for unsolicited interrupts 
a. Digital interrupts (DSS/DRS) 
b. Counter interrupts 
ec. Remote terminal input 


dad. Remote unit or serial line errors 


With the exception of A/D input and remote terminal output, all 
functions are complete upon return to the user's task. 


Under RSX-11M, noninterrupting output functions are immediately 
submitted to the controller through a circular buffer that is filled 
at driver level and emptied at interrupt level. A QIO is considered 
successfully completed when the request is inserted in the circular 


buffer. 
The following operations are in this category: 

1. Bistable digital outputs 

2. Analog outputs 

3. Momentary digital outputs 
Interrupting functions are those operations that generate an interrupt 
within some fixed time after initiation. The driver allows a list of 
multiple transactions to be specified in a single OQIO. Each 
transaction is initiated in sequence without waiting for the preceding 
interrupt, until either the list is exhausted or all modules of the 
specified type are active. The following operations are in this 
category: 


1. A/D inputs 


2. Remote terminal output 
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Unsolicited interrupts may require no initiation by the processor and 
occur at indeterminate intervals. The following functions are in this 
category: 


1. Interrupting digital inputs (DSS/DRS) 

2. Counter modules 

3. Remote terminal input 

4. Error interrupts 
All unsolicited interrupt data, except for errors, may be placed in a 
task-provided circular buffer. On interrupt, an event flag specified 
by the task is set. Such data for each module type is supplied _ to 
only one task per controller. In addition, the driver will activate 
selected tasks on the occurrence of digital or terminal input 
interrupts. 
Error interrupts are described later in this chapter. 
Terminal support is restricted to passing terminal data between the 
device and ae task. The only special character is Control-C (003), 
which may cause a user-specified task to be made active. There is no 
other special processing for terminal I/O except that the parity bit 
is removed. This is similar to the terminal driver function of 
IO.RAL. 

1. MCR is not invoked. 

2. Characters are not echoed. 

3. Carriage control is not performed. 

4. TABs, RUBOUTsS, and so forth are not recognized. 


5. Line terminators are not recognized. 


§. Fill characters are not generated. 


18.1.4 UDC11 Software Compatibility 


Many of the MACRO and FORTRAN interfaces described in the following 
paragraphs are fully compatible with existing UDC11 applications 
software; however, the user should consult Section 18.7 for a summary 
of differences that do exist between UDC and ICS/ICR software. 


18.1.5 Module Addressing Conventions 


Table 18-2 illustrates the relationship between physical slot numbers, 
bus addresses and relative addresses for a given ICS/ICR 
configuration. It is referred to in the following discussion. 


Each A/D converter is assigned a block of 120 channels. The number of 
channels in use within the block depends on the number of multiplexers 
installed. Specifically, each A/D converter has eight channels, and 
each associated multiplexer has 16. 


i] 
i+) 
y 
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Table 18-2 
Sample ICS/ICR Configuration 
Unit: 
Module Slot 
Number | Number Type Bus Address Relative Addresses 


0; 9. D/A converter 171000 0-3. | 
he | 10. A/D converter 171002 0-119. 
2. ye A/D multiplexer jo ------ |  #eHe= 
ag 12 Counter 171006 0 
4. 13. Flip-flop driver 171010 0-15. 
By id, D/A converter ET EOL? 4-7 
Flip-flop driver 171014 1: 
Counter 171016 1 


A/D converter 171020 120.-239. 


As noted, a block of 120 relative addresses is reserved for each A/D 
converter. The converter and multiplexer in slots 10 and 11 contain 
channels 0 through 23. The converter in slot 17 contains channels 120 
through 127. An attempt to access a nonexistent channel (for example, 
channel 30 or channel 129) will be rejected by the driver. 


The user should observe that the bistable drivers in slots 13 and 15 
contain relative point numbers 0 through 15, and 16 through 29 
although the modules are not physically adjacent. In general, the 
relationship between slot number, module type, bus address, and 
relative address is as follows: 


1. A set of contiguous relative addresses is defined for each 
module of a given type that is installed. Each relative 
address, when qualified by type, uniquely identifies a 
digital point or channel. 


2. A set of slot numbers and bus addresses, possibly not 
contiguous, is occupied by all modules of a given type. Such 
addresses may be assigned solely on the basis of hardware and 
installation considerations. Increasing relative addresses 
correspond to increasing bus addresses. 


Table 18-3 is an example of the relationship among bus’ addresses, 
interrupt points, and point numbers for a sample DSS11/DRS11 
configuration. 


Table 18-3 
Sample DSS/DRS Configuration 


160030-160036 
160040-160046 


170010-170016 0 
170020-170026 DSS1il 48 


U1 ¢® 
° 
GQ 
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All addressing is by point number. Except for the interrupts, all 
points are numbered sequentially by type (DSS or DRS), starting with 
the first point on the lowest address assigned to a given module type. 
Interrupt points are defined by means of a 16-bit mask word. Each bit 
in the mask defines an interrupting module; high-order bits 
correspond to increasing bus addresses. 


18.2 LUN INFORMATION 


A request for logical unit information returns the following 
device-dependent data in words 2 through 5 of the buffer: 


WD 02 - 0 
WD 03 - Undefined 
WD 04 - Undefined 
WD 05 - 0O 


18.3 ASSEMBLY LANGUAGE INTERFACE 


Table 18-4 summarizes standard and device-specific QIO functions 
supported by the ICS/ICR driver. Only the five functions indicated by 
a footnote are supported by the DSS/DRS driver. 


Table 18-4 
Summary of Industrial Control QIO Functions 


| gQrose I0.CCI,...,<stadd,sizb,tevf> CONNECT a buffer to 
digital interrupts 
QIOSC IO.CTI,...,<stadd,sizb,tevE, CONNECT a buffer to 
arv> counter interrupts 
QIoSsC IO.CTY,...,<stadd,sizb,tevf> CONNECT a buffer to 
terminal interrupts 
QIOSC LOST o siex Disconnect a buffer from 
di ital interrupts 
OIOSC ELOSDTT e44 Disconnect a buffer from 
counter interrupts 
QIOSsc LOCDTV 5 aac Disconnect a buffer from 
terminal interrupts 
QIOSC TO. FEN |. a Set controller off line 
QIOSC LO. EEL ps ay Sn pPCo INITIALIZE a counter 
| QTOSC IO.LDI,...,<tname,[,tevf], | LINK task to digital | 


on,csm>l 


interrupts 


QITOSC IO.LKE,...,<tname,[,tevf]> LINK task to error 


interrupts 


(continued on next page) 
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Table 18-4 (Cont.) 
Summary of Industrial Control QIO Functions 


Format Function 


QIOSC TO. LTI, sss, thname, ftevet] LINK task to counter 
en[,arv]> interrupts 
OIOSC IO.LTY,.<«,;<thame, {,tevil> LINK task to remote 


QIosc IO.MLO,...,<opn,pp,dp>1 | OPEN or close bistable 
digital output points 


QIOSC LO; MSO, «s:<¢9<SOpn,d p> PULSE momentary digital 
output points 


terminal interrupts 


QIOSC IO.NLK,...,<tname>1t UNLINK a task from all 
interrupts 

QIOSC Oe ON by sss Place ICS/ICR controller 
online 

QIOsc IO.RAD,...,<stadd>1 READ activating data 

QIosc IO.RBC,...,<stadd,size, INITIATE multiple A/D 

stcnta> conversions 
QIOSC IO.SAO,...,<chn,vout> PERFORM analog output 


QIOSC IO.UDI,...,<tname>1t UNLINK a task from 


digital interrupts 


OIOSC UNLINK a task from error 


interrupts 


IO.UER,...,<tname> 


UNLINK a task from 
counter interrupts 


OQOIOSC IO.UTI,...,<tname> 


UNLINK a task from 
terminal interrupts. 


QIOSC IO.UTY,...,<tname> 


TRANSMIT data to the ICR 
remote terminal 


QIOSC IO.WLB,...,<stadd,sizb> 


1. These functions are supported by the DSS/DRS driver. 


arv 
The starting address of a buffer containing initial or reset 
counter values. The buffer must be aligned on a word boundary. 
chn 
The D/A channel number. 
cn 


The counter number. 
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csm 
The change-of-state mask. 

dp 
The binary data pattern. 

ic 
The initial count. 

mn 
The module number. 

opn 
The first bistable (latching) digital output point number. This 
value must be on a module boundary (evenly divisible by 16). 

pn 
The point number (must be assigned on a module boundary). 

Pp 
A 16-bit mask. 

sizb 
The data buffer size in bytes. For a circular buffer connected 
to unsolicited interrupts, this value must be even and large 
enough to include one entry plus the 2-word header. 

size 
The data and control buffer size in bytes. This value must be an 
even number that is greater than 0. 

stadd 
The starting address of the data buffer (must be on aé_e word 
boundary). 

staddb 


The starting address of the terminal output buffer (may be 
aligned on a byte boundary). 


i 
10 ¢) 
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stcnta 


The starting address of the control buffer (must be on a_e word 
boundary); each control buffer word must be constructed as 
described in Table 18-5 (Section 18.3.2). 


tev£ 
An event flag number in the range 0 to 96, (if the group-global 
event flag SYSGEN option was selected), or 0 to 64 if 
group-global event flags are not supported. 
tname 
A task name composed of 1 to 6 alphanumeric characters in a 
2-word RADIX-50 format. Two arguments, each containing three 
characters, are required for this parameter. For example, the 
task name ICNAME is specified as: 
<“RICN,~ RAME,...> 
If the task name is less than four characters, a null argument 
must be specified as follows for task ABC: 
<°“RABC,,...> 
vout 


A binary number between 0 and 1023. that is to be converted to 
an analog output. 


The following sections contain a detailed description of each 
function. In the discussion of QIO request parameters, the following 
conventions apply. 


All numbering is relative. 


Module numbers start at 0 beginning with the first module of a given 
type. Increasing module numbers correspond to increasing physical bus 
addresses. 


Channel numbers start at 0, with channel O as the first channel on the 
first module of a given type. 


Point numbers start at 0 with point 0 as the first point on the first 
module of a given type. Points within a module are numbered "from 
right to left" in increasing order. 


It should be remembered that there is no requirement for ICS/ICR 
modules of a given type to occupy contiguous slots; thus, for 
example, digital points 15(10) and 16(10) need not reside on 
physically adjacent modules. This restriction does apply to DSS/DRS 
modules, however. 


Leis 
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It is assumed that the number of points or channels per module is a 
constant for each generic type. Specifically, the following weights 
apply: 


1. Each ICS/ICR Digital I/O Module contains 16 points. 

2. Each DSS/DRS Digital I/O Module contains 48 points. 

3. Each, Counter Module contains 1 channel. 

4. Each D/A Module contains 4 channels. 

5. Each A/D Converter contains 120 channels. 
As stated above, an A/D converter is assigned a block of 120 channels. 
The number of channels in use within the block depends on the number 


of multiplexers installed. The driver will reject an attempt to 
address a nonexistent channel. 


18.3.1 General Error Status Returns 


The system recognizes and handles two kinds of status conditions when 
they occur in I/O requests: 


e Directive conditions, which indicate the acceptance or 
rejection of the QIO directive itself 


e I/O status conditions, which indicate the success or failure 
of the I/O operation 


Table 18-7 lists numerical values of returns for both assembly 
language and FORTRAN interfaces. 


The following directive and I/O status returns apply uniformly to all 
requests. 


18.3.1.1 Directive Conditions 


IS.SUC - Directive accepted. The first six parameters of the QIO 
directive were valid, and sufficient dynamic memory was 
available to allocate an I/O packet. The directive is 
accepted. 

IE.ADP - Invalid address. The I/O status block or the QIO DPB’ was 
outside of the issuing task's address space or was not 
aligned on a word boundary. 

IE. IEF - Invalid event flag number. 

IE.ILU - Invalid logical unit number. The lun specification in a_  QIO 


directive was invalid for the issuing task. For example, 
there were only five logical unit numbers associated with the 
task, and the value specified for lun was greater than five. 


IE.NOD 


ITE.SDP 


ITE.ULN 


Lee Sebs 


IE. ABO 


IE.OFL 


IE.DNR 


IE.IFC 
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Insufficient dynamic memory. There was not enough dynamic 
memory to allocate an I/O packet for the I/O request. The 
user can try again later by blocking the task with a WAITFOR 
SIGNIFICANT EVENT directive. Note that WAITFOR SIGNIFICANT 
EVENT is the only effective way for the issuing task to block 
its execution, Since other directives that could be used for 
this purpose themselves require dynamic memory for their 
execution (for example, MARK TIME). 


Invalid DIC number or DPB size. The directive identification 
code (DIC) or the size of the directive parameter block (DPB) 
was incorrect; the legal range for a DIC is from 1 through 
127, and all DIC values must be odd. Each individual 
directive requires a DPB of a certain size. If the size is 
not correct for the particular directive, this code is 
returned. 


Unassigned LUN. The logical unit number in the QIO directive 
was not associated with a physical device unit. The user may 
recover from this error by issuing a valid Assign LUN 
directive and then reissuing the rejected directive. 


I/O Conditions 


Operation aborted. The specified operation was canceled by 
IO.KIL or the request timed out while the unit was off line. 


Controller off line. The physical device unit associated 
with the LUN specified in the QIO directive was not on line. 
An ICS/ICR controller may be off line because a device check 
during bootstrap load has indicated that the controller is 
not in the configuration. 


Controller not ready. A nonrecoverable controller error has 
been detected. 


Tllegal function. A function code was included in an I/O 
request that is illegal for the ICS/ICR. The function may 
also refer to an ICS/ICR module type or function that was not 
specified during system generation. 


A/D Input - Read Multiple A/D Channels 


This function provides the capability of reading several A/D channels 
at any permissible gain. The driver is capable of initiating parallel 
transfers when more than one A/D converter is installed in a file box; 
however, 
may be in progress at a given time. 


only one interrupt module request (remote terminal or A/D) 


QIO DPB format: 


QIOSC IO.RBC,...,<stadd,size,stcnta> 
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stadd 
The starting address of the data buffer (must be on a word 
boundary). 

size 
The data buffer size in bytes (must be even and greater than 0); 
the control buffer is the same size. 

stcnta 
The starting address of the control buffer (must be on a_ word 


boundary); each control buffer word must be constructed as shown 
in Table 18-5. 


Return Status: 


IS.SUC - Function successfully completed. 

IE.BAD - Illegal channel or gain code specified: 

IE.BYT - Data buffer is byte aligned. Alternatively, the length 
of the buffer is not an even number of bytes. 

IE.DNR - Device not ready. A/D converter interrupt time-out 


occurred, 


Note that the second I/O status word contains a count of the 
number of conversions successfully completed. 


One control word is paired with each data word. That is, the data 
appearing in a data array element is obtained using the gain and 
channel number specified in the corresponding element of the control 
array. Control words specify the gain and channel in the format shown 
in Table 18-5. 


Upon receiving and validating the parameters within the I/0 packet, 
the driver will initiate the following sampling procedure: 


1. The control word is fetched and tested for validity (that is, 
for legal gain and channel). If an error is encountered or 
no further control words remain, processing is terminated as 
described in Step 4. 


2. Assuming the A/D converter board is idle, the driver starts 
the conversion, sets this resource busy, and returns to step 
1. If the converter is busy, the driver returns control to 
the system after saving the data required to initiate the 
conversion when the channel becomes idle. 


3. On the occurrence of an A/D interrupt, the interrupt service 
routine initiates the appropriate processing at the non 
interrupt level that will either set the channel idle or 
initiate a previous request stored during step 2. The 
occurrence of the latter results in processing of additional 
control words as described in step l. 
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Table 18-5 
A/D Conversion Control Word 


Channel Number range: 0-1919 


Gain value for Gain 
this sample. The 
binary value is 


as follows: 


1 

2 
illegal 
illegal 


illegal 
illegal 
50 
100 
illegal 
illegal 
200 
1000 
illegal 
illegal 


KH HE HYPE rEHOOOOOO0OO 
RPrHeEHOODOOREHFHOOCOO 
KPHOOHRFPOOFRPFOOHRHOO 
HOHOHFOHPOFRFOHFOFRFOFO 


4. The converted value is returned as 12 bits, left-justified, 
in a 16-bit word, with the low-order 4 bits set to 0. 


5. A/D requests are terminated under any of the _ following 
conditions: 


a. All control words have been processed. 
b. A hardware error has occurred. 
c. An error in a control word has been detected. 


Regardless of the cause, the driver cannot complete request processing 
until all pending A/D transfers have gone to completion. 


Because of overlapped processing, multiple errors can occur (for 
example, a hardware error and an erroneous control word). The driver 
returns the status associated with the earliest transaction that 
caused an error condition. Thus, at the user interface, the driver 
appears to execute all conversions sequentially. 


18.3.3 Analog Output 


This function provides the capability of setting a single analog 
output channel to a specified voltage. 
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The driver will allow continual monitoring for digital, counter, and 
terminal inputs with the provision that, for each controller, only one 
task per module type may receive such inputs. 


Task activation is permitted for digital, terminal, and error 
interrupts. The processing related to hardware errors is discussed in 
Section 18.5. Activation of tasks by digital, counter, and terminal 
inputs is covered in Section 18.3.7. 


The driver functions described in the following paragraphs allow a 
task to continually receive interrupt data. To monitor such data, a 
task must provide: 


1. A buffer that is filled by the driver and emptied by the task 
in circular fashion 


2. An event flag that will be set upon the occurrence of each 
interrupt 


The driver will connect a single task per controller to receive 
interrupts from a specific module type. 


The buffer to be connected has the format shown below: 


FORTRAN 
Index Contents 
1 driver index 
2 user index 
3 word 0 of entry 
4 word 1 of entry 


The buffer consists of a 2-word header containing the driver and user 
index, aas shown, followed by a data area that is subdivided into 
fixed-length entries. Each entry consists of a word containing the 
entry existence indicator followed by one or more words of 
device-dependent data. Such information usually consists of module 
data, relative module number, and a code identifying a module type. 
On the occurrence of an interrupt, the driver enters data in the 
location currently indicated by the driver index. This index can be 
considered as a FORTRAN index into the buffer. That is, the first 
location in the buffer is associated with the index 1. The beginning 
of the data area is associated with the first entry, index 3. Entries 
are made in a circular fashion starting at the beginning of the data 
area, filling in order of increasing memory address, and wrapping 
around to the beginning of the data area when there is insufficient 
space for an entry at the end. Note that the size of the data area 
must be an integer multiple of the entry size. 


It is expected that the connected task will maintain the user index, 
ensuring that it indicate where, in the buffer, the task is to process 
interrupt data next. 


When the task is activated by the driver, it should process data in 
the buffer starting at the location indicated by its pointer, and 
continuing in circular fashion until an existence indicator is 
encountered that is 0. 
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The existence indicator is set to +1 when a buffer entry is made. 
Except to record a hardware error, the contents of an entry are not 


altered by the driver if the indicator is nonzero. . Hence, when a 
requester has removed or processed the entry, he must clear the 
existence indicator in order to free the buffer entry position. Tf 


the driver detects a nonzero indicator, (that is, data input has 
occurred in a burst sufficient to overrun the buffer), the data is 
discarded and a count of data overruns is incremented. The count is 
maintained in the entry existence indicator, which, as noted above, is 
set to +1 to indicate no overruns between entries, +2 to indicate a 
hardware error entry, or a negative value recording the two's 
complement of the number of times data has been discarded between 
entries. The overrun count will never be allowed to wrap around to a 
positive value. 


In the event of a nonrecoverable controller error (remote unit 
power-fail or hard data error) all connected tasks are activated with 
the following entry in the circular buffer: 


WD 00 Hardware error indicator (+2) 
WD nn Contents of ICSR register 

WD nn+1l Physical unit number 

WD nn+2 Generic code indicator 


set to 177770(8) 


nn 
The offset to module data word. 


This entry is always placed in the buffer regardless of overflow 
status. 


The error flags are obtained from the controller ICSR word at the time 
the error was detected (see Table 18-7). 


18.3.6.1 Connect to Digital Interrupts - This function allows a 
single task to receive digital interrupt data. 


QIO DPB format: 


QIO IO.CCI,...,<stadd,sizb,tev£f> 


stadd 
The starting address of buffer to be connected (must be _ word 
aligned). 

sizb 
The length of buffer in bytes (must be even). Minimum buffer 
length is 14 bytes. 

tev£t 


The trigger event flag number. 
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Return Status: 


IS.SUC Function successfully completed. Second I/O status word 
contains the number of words passed per interrupt in the 
low byte, and the initial FORTRAN index in the high 


byte. 


IE.BYT - Buffer address is byte aligned or length is an _ odd 
number of bytes. 


IE.CON - Interrupt already connected to another task. 
IE,IEF - Invalid event flag number. 
TE.PRI - Task checkpointable and not fixed in memory. 


IE.SPC - Interrupt circular buffer was not wholly within the 
address space of the task. Alternatively, the buffer 
was too small For a single data entry (seven words 
minimum). 


Entry Format: 


WD 00 - Existence Indicator 

WD 01 - Change of state indicator 

WD 02 - Module data 

WD 03 - Relative module number 

WD 04 - Generic Code l, 2, or 3, indicating a digital interrupt 


The contents of the existence indicator have been described 
previously. 


The change-of-state indicator records those bits for which a change of 
state in the direction of interest has been detected. The direction 
of the change may be from 0 to 1 (point closed (PCL)) or 1 to 0 (point 
open (POP)) depending upon the PCL or POP jumper connections on the 
digital interrupt module. The driver will assume that at least one of 
these signals is always asserted. 


The relative module number indicates the module on which the change of 
state was recognized. 


The module data word records data received at the time the interrupt 
was serviced. 


The generic code identifies the type of module that caused the 


interrupt. A digital interrupting module may have the value 1, 2, or 
3 as selected by user-installed jumpers on the module. 


18.3.6.2 Disconnect from Digital Interrupts - This function allows a 
task to terminate the processing of digital interrupt data. 


QIO DPB format: 


OLOSC: LO.DEL;, Seve 
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Return Status: 


IS.SUC ~- Function successfully completed. Second I/O status word 
is 0. 


IE.CON - Task was not connected. Second I/O status word is 0. 


18.3.5.3 Connect to Counter Module Interrupts - This function allows 
a Single task to receive counter interrupt data. 


OIO DPB format: 


orose Io, 


Q 


TI,...,<stadd,sizb,tevf,arv> 


stadd 


The starting address of circular buffer (must be word aligned). 


sizb 
The length of buffer in bytes (must be even). Minimum buffer 
length is 12 bytes. 

tevf 
The trigger event flag number. 

arv 
The starting address of table of initial counter values (must be 
word aligned). 

Word 03 defines an array of initial counter values. One entry is 


required for each counter installed in a physical unit. Entries are 
paired with modules in logically ascending sequence. The counter is 
set to the initial value upon receipt of the connect function and 
whenever an overflow interrupt occurs (that is, when the count reaches 
0). 


Return Status: 

IS.SUC - Function successfully completed. The second I/O status 
word contains the number of words passed per interrupt 
in the low byte, and the initial FORTRAN index in the 
high byte. 


IE.BYT - Buffer address is byte aligned or length is an odd 
number of bytes. 


IE.CON - Interrupt already connected to another task. 
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IE.IEF - Invalid event flag number. 

IE.PRI -—- Task checkpointable and not fixed in memory. 

IE.SPC - Interrupt circular buffer or table of initial values was 
not wholly within the address space of the task. 
Alternatively, the buffer was too small for a_e single 
data entry (six words minimum). 

Entry Format: 
WD 00 - Existence indicator 


WD 01 Module data 


WD 02 - Relative module number 


WD 03 


Generic code (4, 5, or 6) 


18.3.6.4 Set Counter Initial Value - This function allows a counter 
initial value to be established. A task need not be connected to 
counter interrupts to perform this function. 

QIO DPB format: 


QIOSC. TOLITL «s/s p <n -C> 


mn 


The relative module number. 


ic 


The new initial count. 


Return Status: 


IS.SUC - New value submitted for output to the controller. The 
second word of I/O status is set to 0. 


IE.MOD - Nonexistent module number specified. 
Upon receipt of the request, the new initial value is immediately 
queued for output to the controller. The counter is reinitialized 


with this value on overflow if a task is connected to counter 
interrupts. 


18.3.6.5 Disconnect from Counter Interrupts - This function allows a 
task to terminate counter interrupt processing. 


QOIO DPB format: 
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Return Status: 


IS.SUC - Function successfully completed. The second word of I/0 
status is set to 0. 


IE.CON - Task was not connected to timer interrupts. 


After disconnect is complete, counters are not reset to the initial 
value at the time of the interrupt. 


18.3.6.6 Connect to Terminal Interrupts - This function allows a task 
to receive terminal inputs from the selected ICR11 controller. 


QIO DPB format: 


QIOSC IO.CTY,...,<stadd,sizb,tevf> 


stadd 


The address of the circular buffer (must be word aligned). 


sizb 
The length of buffer (must be even). The minimum buffer length 
is 12 bytes. 

tevt 


The trigger event flag number. 


Return Status: 


IS.SUC 


Function successfully completed. The second I/O status 
word contains the number of words passed per interrupt 
in the low byte, and the initial FORTRAN index in _ the 
high byte. 


IE.BYT - Buffer is byte aligned or length is an odd number of 
bytes 


IE.CON - Interrupt already connected to another task. 

IE.IEF - Invalid event flag number. 

TE.MOD - Nonexistent device. Controller is ICS1l. 

IE.SPC - Interrupt circular buffer was not wholly within the 
address space of the task. Alternatively, the buffer 
was too small for a single entry (six words minimum). 

Entry Format: 

WD 00 - Existence indicator 

WD 01 - High byte = 0, low byte = terminal input character 

WD 02 - Relative module number (normally 0) 


WD 03 - Generic code indicator (normally 0) 
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Note that words 2 and 3 are nonzero only when the entry was made as 
the result of a nonrecoverable controller error. 
All remote terminal data is conveyed to the requesting task as input, 
but with the parity bit removed. 
NOTE 


Remote terminal input is not echoed by 
the driver. 


18.3.6.7 Disconnect from Terminal Input - This function allows a task 
to discontinue the processing of terminal input. 


QIO DPB format: 


OLOSC TO. DTY » <5 


Return Status: 


IS.SUC - Function successfully completed. The second word of I/0 
status is set to 0. 


IE.CON - Task was not connected to remote terminal interrupts. 


18.3.7 Activating a Task by Unsolicited Interrupts 


The functions described in the following paragraphs provide the 
capability of: 


1. Activating a task in response to unsolicited interrupts 


2. Interrogating the driver to determine the reason for 
activation 


3. Removing a task from the activation list 
The QIO DPB parameters specify the task name, an optional trigger 
event flag to be set if the task is active, and device-dependent 
Parameters that identify the interrupt source. A task is linked to 
interrupts (that is, made eligible for activation) provided that: 

1. The resource exists. 

2. The task is installed. 

3. No other task is linked to the resource. 
If another task is linked to the resource, the driver will reject the 
request with a status of resource-in-use (IE.RSU). A resource is 


defined as a single interrupt point, remote terminal (Control-C input 
only), or counter module. 
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On the occurrence of the appropriate interrupt, the task is made 
active if dormant; otherwise, a trigger event flag, if specified, is 
set. The task may interrogate the driver to determine the conditions 
that caused activation, and to signify interrupt recognition. The 
function of the event flag is to allow such a task to recognize an 
event that has occurred while the task was active. Recognition is 
ensured prior to the completion of task execution by issuing the Exit 
If system directive followed by the Clear Event Flag directive. 


The linkage between a task and a specific interrupt is removed by 
issuing the appropriate unlink request with the QIO directive. 


Only one task may be associated with each interrupt source (that is, 
one task per digital interrupt point, terminal input, or counter 
module. 


NOTE 


The MCR command REMOVE automatically 
unlinks a task from all interrupts. 


18.3.7.1 Link a Task to Digital Interrupts - This function allows a 
task to be activated on the occurrence of digital interrupts. 


QIO DPB format: 


QTOSC IO.LDI,...,<tname,[,tevf],pn,csm> 


tname 


A 1- to 6-character alphanumeric task name in 2-word, Radix-50 
format. 


tevf 

The trigger event flag (0 = none). 
pn 

The point number (must be aligned on a module boundary). 
csm 


The change-of-state mask. 


The change-of-state mask indicates those bits for which a change of 
state in the direction specified by the PCL and POP jumpers causes the 
task to be activated. Only one task may be linked to a given 
interrupt point. A 0 change-of-state mask is not permitted. 
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Return Status: 


IS.SUC 


Function successfully completed. The second word of I/0 
Status is set to 0. 


IE.BAD - Change-of-state mask set to 0. 
IE.IEF - Invalid event flag number. 


IE.MOD - Nonexistent module or point not aligned on a module 
boundary. 


IE.NOD - Insufficient dynamic memory to allocate secondary 
control block. 


IE.NST - Task "tname" is not installed. 


TE.RSU - One or more of the specified points is in use by other 
tasks. 


18.3.7.2 Link a Task to Counter Interrupts - This function allows a 
task to be activated by means of an interrupt from a single counter 
module. 

QIO DPB format: 


QIOSC IO.LTI,...,<tname,[,tevf],cn[,ic]> 


tname 


A 1- to 6-character alphanumeric task name in 2-word Radix-50 
format. 


tevf 

The trigger event flag (0 = none). 
cn 

The relative module number. 
ic 


The counter value (optional). 
The counter value if nonzero, is used to reinitialize the module in a 
manner similar to that described for the Set Counter function in 
Section 18.3.6.4. Initialization may be bypassed by setting this 
parameter to 0. 


Return Status: 


IS.suc - Function successfully completed. The second word of I/0 


. 
status is set tc QO. 


IE,IEF - Invalid event flag number. 
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IE.MOD - Nonexistent module specified. 


TE.NOD - Insufficient dynamic memory to allocate a secondary 
control block. 


IE.RSU —- Counter is linked to another task. 


18.3.7.3 Link a Task to Terminal Interrupts - This function allows a 
task to be activated by means of an interrupt from a remote terminal. 
The task will be activated only in response to the Control-C character 
(octal 003). 

QTO DPB format: 


QIOSC IO.LTY,...,<tname,[{,tevf]> 


tname 
A l- to 6-character alphanumeric task name in 2-word, Radix-50 
format. 

tevf 


The trigger event flag (0 = none). 


Return Status: 


IS.SUC 


Function successfully completed. The second word of I/0 
status is 0. 


IE.IEF - Invalid event flag number. 
IE.MOD - Nonexistent module (unit is ICS11 controller). 


IE.NOD - insufficient dynamic storage to allocate secondary 
control block. 


IE.NST - Task "tname" is not installed. 


IE.RSU - Remote terminal is linked to another task. 


18.3.7.4 Link a Task to Error Interrupts - This function allows a 
single task to be activated whenever a remote unit power-fail or 
nonrecoverable serial line error is detected on any or all_ remote 
units in a= system. Only one task within a system may be linked to 
error interrupts. Once linked, the selected task may receive error 
reports from any ICR controller. 


QIO DPB format: 


QIOSC IO.LKE,...,<tname,[,tevf]> 
tname 


A l- to 6-character alphanumeric task name in 2-word Radix-50 
format. 
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tevft 


The trigger event flag (0 = none). 


Return Status: 


IS.SUC - Function successfully completed. The second word of I/0 
Status is 0. 


IE.IEF - Invalid event flag number. 
IE.IFC - No ICR11 subsystems are installed. 


IE.NOD - Insufficient dynamic storage to allocate secondary 
control block. 


IE.NST - Task "tname" is not installed. 


IE.RSU - Another task is linked to error interrupts. 


18.3.7.5 Read Activating Data - This function allows a task to 
determine the conditions that caused it to be activated. 


QOIO DPB format: 


QIOSC IO.RAD,...,<stadd> 


stadd 


The address of 6-word buffer to receive activation data (must be 
word aligned). 


The buffer receives data in the following format: 


WD 00 - Activation indicator 

WD 01 - Physical unit number 

WD 02 - Generic code 

WD 03 - Relative module number 
WD 04 - Hardware dependent data 
WD 05 -—- Hardware dependent data 


The activation indicator is similar in function to the existence 
indicator used when reading circular buffer entries. The indicator is 
set to +1 on the occurrence of an interrupt to which the requesting 
task is linked, and the appropriate data is stored. The indicator is 
cleared when the data is solicited by the task. If an interrupt 
linked to the task occurs and the parameter is nonzero then the 
previously stored data is not modified and the driver sets this 
element with the two's complement of the number of linked interrupts 
not recorded. 


interrupt. 
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The generic code is identical to that specified for circular buffer 
entries, namely: 


0 ~ Terminal (Control-C) 
1,2,3 - Digital interrupt 
4,5,6 - Counter interrupt 
177770 - Fatal controller error 


Hardware-dependent data is associated with generic code and will 
consist of the following: 


Terminal: 
WD 04 - Terminal buffer contents (low byte) 
WD 05 - Undefined 


Digital Interrupts: 


WD 04 —- Module data 

WD 05 - Change-of-state indicator 
Counter: 

WD 04 -—- Module data 

WD 05 —- Undefined 


Fatal Controller Error: 
WD04 - Contents of ICSR register (see Table 18-7) 


WD05 - Contents of ICAR register (See Table 18-8) 


Return Status: 


IS.SUC - Function successfully completed. The second word of I/O 
status is 0. 
IE.BYT - Buffer address is aligned on an odd byte boundary. 


IE.NLK - Task “tname" was not linked to interrupts. 


IE.SPC - Buffer not totally within the task's address space. 


18.3.8 Unlink a Task from Interrupts 


The functions described in the following paragraphs provide the 
capability of: 


1. Unlinking a task from all interrupts on a controller 


2. Selectively unlinking a task from interrupts by module type 
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18.3.8.1 Unlink a Task from All Interrupts - This function unlinks a 
task from all interrupts on a egiven controller and from error 
interrupts. 

QIO DPB format: 


QIOSC IO.NLK,...,<tname> 


tname 
A 1- to 6-character alphanumeric task name in 2-word Radix-50 
format. 

Return Status: 


IS.SUC - Function successfully completed. The second word of I/0 
Status is 0. 


IE.NLK - Task "tname" was not linked to interrupts. 


18.3.8.2 Unlink a Task from all Digital Interrupts - This function 
provides the capability of unlinking a task from all digital interrupt 
points on a controller. 

QIO DPB format: 


QITOSC IO.UDI,...,<tname> 


tname 


Pa 


a l- to 6-character alphanumeric task name in 2-word Radix-50 
format. 


Return Status: 


IS.SUC - Function successfully completed. The second word of I/0 
Status is 0. 
IE.NLK - Task "tname"™ was not linked to the specified class of 
interrupt. 
IE.NST - Task not installed. 
IE.MOD - Nonexistent module type specified. 
18.3.8.3 Unlink a Task from Counter Interrupts - This function 


provides the capability of unlinking a task from all counter module 
interrupts. 


QIO DPB format: 


QIOSC IO.UTI,...,<tname> 


tname 


A l- to 6-character alphanumeric task name in 2-word Radix-50 
format. 
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Return Status: 


IS.SUC - Function successfully completed. The second word of I/O 
Status is 0. 


IE.NLK - Task "tname" was not linked to the specified interrupts. 
IE.NST - Task not installed. 
IE.MOD - Nonexistent module type specified. 

18.3.8.4 Unlink a Task from Terminal Interrupts - This function 


provides the capability of unlinking a task from terminal interrupts. 
QIO DPB format: 

QIOSC IO.UTY,...,<tname> 
tname 

A 1- to 6-character alphanumeric task name in 2-word Radix-50 


format. 


Return Status: 


IS.SUC - Function successfully completed. The second word of I/0 
Status is 0. 

IE.NLK - Task "tname" was not linked to the specified interrupts. 

IE.NST - Task not installed. 

IE.MOD - Nonexistent module specified (that is, device is an 


ICS11 controller). 


18.3.8.5 Unlink a Task from Error Interrupts - This function provides 
the capability of unlinking a task from all error interrupts. 


QIO DPB format: 
QIOSC IO.UER,...,<tname> 
tname 
A 1- to 6-character alphanumeric task name in 2-word Radix-50 


format. 


Return Status: 


IS.SUC - Function successfully completed. The second word of I/0 
Status is 0. 

IE.IFC - No ICR11 controllers exist in the system. 

IE.NLK - Task "tname" was not linked to error interrupts. 


IE.NST - Task not installed. 
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18.3.9 Terminal Output 


This function allows a task to perform output to the terminal device. 
Characters are output exactly as they appear in the buffer. The 
carriage control parameter is not recognized. It should be noted that 
only one interrupt module request per controller (terminal or A/D) may 
be in progress at a given time. Thus, the driver will not initiate an 
A/D operation on a given controller, until any terminal output in 
progress for that controller has been completed. 


QIO DPB format: 


QIOSC IO.WLB,...,<staddb,sizb> 


staddb 


The buffer address (may be odd). 


The byte count (may be odd). 


Return Status: 


IS.SUC - Function successfully completed. Second word of TI/0 
status contains the number of bytes output. 


IE.MOD - Nonexistent hardware function. Request was issued for 
an ICS11 controller. 


18.3.10 Maintenance Functions 


The functions described below allow a privileged task to enable and 
disable error reporting while troubleshooting or maintenance on a 
remote unit is in progress. 


18.3.10.1 Disable Hardware Error Reporting - This function allows a 
privileged task to disable error reporting and error interrupts, and 
restrict access to the controller while remote unit troubleshooting or 
module calibration is in progress (see Section 18.5.1). Upon receipt 
and validation of the request, error interrupts are disabled and 
subsequent controller time-outs are ignored. The occurrence of device 
time-out while A/D conversion or remote terminal input is in progress 
results in termination of the request with the error code IE.ABO. 
When error reporting is disabled in this manner, access to. the 
controller for input or output to I/0 modules is restricted to 
privileged tasks. All other requests not requiring the transmission 
of data to or from the device are permitted for all tasks. Such 
requests are as follows: 


1. Disconnect from digital, counter, or remote terminal 
interrupts 
2. Unlink from interrupts 


3. Read activating data 
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4. Link to digital, remote terminal, or error interrupts 
5. Connect a buffer to digital or remote terminal interrupts 


All other requests not issued by a privileged task are rejected with 
the error code IE.DNR. 


QOIO DPB format: 


OLOSC -10,FEN» 6 


Return Status: 


IE.FLN - Unit already off line 


IE.PRI - Task not privileged 


18.3.10.2 Enable Hardware Error Reporting - This function allows a 
privileged task to enable error reporting and device error interrupts. 
Upon receipt and validation of the function, all device error 
interrupts are enabled and the unit is marked on line. These actions 
are performed regardless of the current state of the unit. QIO DPB 
format: 


OIOSC: 10.O0NL, 2: 


Return Status: 
IS.Suc - Function successfully completed 


IE.PRI - Task not privileged 


18.3.11 Special Functions 


18.3.11.1 1/0 Rundown - An I/O rundown request from the Executive 
will automatically cause the task to be disconnected from all 
interrupts. The rundown operation is not finished until any A/D input 
in progress for the task has been completed. 


18.3.11.2 Kill I/O - The kill I/O function allows a task to initiate 
I/O rundown processing for itself on any device. Request processing 
is identical to that described for I/O rundown. 

QIO DPB format: 


OLTOSO TOcKL EY << 


Return Status: 


IS.SUC - Function successfully completed 
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18.4 FORTRAN INTERFACE 


Table 18-6 lists the FORTRAN interface subroutines supported for the 
ICS/ICR subsystem. (D) indicates a direct access call. The six 
subroutines supported by the DSS/DRS driver are indicated by a 
footnote. 


Unless specifically noted, all subroutines are reentrant (but not 


necessarily position-independent) and may be placed in an absolute 
resident library. 


Table 18-6 
FORTRAN Interface 


Function 


Input analog data from multiple channels in random 
sequence 


Subroutine 


AIRD/AIRDW 


status 


AISQ/AISQW Read a series of sequential analog input channels 
at random gain 

AO/AOW Perform analog output on several channels 

| ASICLN/ Assign a LUN to an ICS/ICR controller 

ASUDLN 

ASISLNL Assign a LUN to a DSS/DRS controller 

CTDI Connect a circular buffer to receive digital 
interrupt data 

CTT Connect a circular buffer to receive counter 
interrupt data 

CTTY Connect a circular buffer to receive ICR11 remote 
terminal data 

DFDI Disconnect a buffer from digital interrupts 

DFTI Disconnect a buffer from counter interrupts 

DFTY Disconnect a buffer from remote terminal interrupts 

DI/DiIwL Read several 16-point digital sense fields (D) 

DOL/DOLWL Latch or unlatch several 16-point bistable output 
fields 

DOM/DOMW Pulse multiple 16-point momentary digital output 
fields 

LNK 1 Link a task to unsolicited interrupts 

OFLIN Suppress error reporting. Place unit in not ready 

| | | 


Enable 
status 


error reportins. Return unit to read. 
vr y ; 


Read a Single digital interrupt point (D) 


(continued on next page) 
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Table 18-6 (Cont.) 
FORTRAN Interface 


subroutine | umeton 


Read interrupt activation data 


Read the digital interrupt circular buffer 
Read the counter interrupt circular buffer 
Read digital interrupt circular buffer; re 
data on only those points for which a chang 


State has been recognized 


Read digital interrupt circular buffer; return a 
full data word 


RDWD 


RSTI Read a single counter module (D) 


RTO/RTOW Perform output to a remote ICR11 terminal 


UNLNK1+ Unlink a task from unsolicited interrupts 


1. These subroutines are supported by the DSS/DRS driver. 


18.4.1 Synchronous and Asynchronous Process Control I/0 


The Instrument Society of America (ISA) standard provides for 
synchronous and asynchronous I/0. Synchronous I/0 is indicated by 
appending a W to the name of the subroutine (for example, AO/AOW). 
Except for analog input and terminal output, all QIOs issued by the 
process control subroutines are serviced immediately by the driver and 
are complete upon return to the issuing task. In such cases, there is 
no functional difference between the synchronous and asynchronous 
forms; however, both forms of the name are recognized. In the case 
of A/D input and terminal output, the subroutines are functionally 
distinct. If the asynchronous form is used, execution continues and 
the calling program must periodically test the status word for 
completion. 


18.4.2 Return Status Reporting 


The I/O status parameter is a 2-word integer array. The first element 
of the array receives the status of the FORTRAN call in accordance 
with ISA convention. 


This array serves two purposes: 


1. It is the 2-word I/O status block to which the driver returns 
an I/O status code on completion of an I/O request. 


2. The first word of the status block receives a status code 
from the FORTRAN interface subroutine in ISA-compatible 
format, with the exception of the I/0 pending condition, 
which is indicated by a status of 0. The ISA standard code 
for this condition is +2. 
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For asynchronous analog input and terminal output, status is set by 
means of an asynchronous trap; therefore, the trap mechanism must be 
enabled while these functions are in progress. 


For compatibility, the 2-word status block is also required for status 
returned by the direct access calls. Errors of this type that may be 
returned are: 


Word 1 


3 Number of points requested is 0. 


Word 1 


+321 Invalid ICS/ICR module. 


The status code must be interpreted in the context of the function 
requested; however, the following general conditions will apply: 


Contents of Status Word 1 Meaning 
0 Operation pending, I/0 in progress 
+1 Successful completion 
+3 Error in a calling argument has’ been 


Aetected by the interface subroutine 


3<Word 1<300. QIO directive rejected. Actual error 
code = -(WORD 1 - 3) 

Word 1 > 300 Request rejected by driver. Actual 
error code = -(WORD 1 - 300) 


Table 18-7 lists all possible status values: the FORTRAN value, 
assembly language mnemonic, actual value, and related definition. 


Table 18-7 
Return Status Summary 


FORTRAN Assembly Assembly 
Interface Language Language Definition 
Value Value Mnemonic 
IS. PND Operation pending 


IS.SUC Successful completion 


none Error detected in FORTRAN 
calling sequence 


IE.UPN Insufficient dynamic storage 
to allocate I/0 packet 


IE.ULN Unassigned LUN 


IE.LNL LUN usage interlocked 


| +99 | -96 | IE.ILU Invalid LUN | 
+100 -97 TE..LBF Invalid event flag number 


(continued on next page) 
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Table 18-7 (Cont.) 
Return Status Summary 


FORTRAN Assembly Assembly 
Interface Language Language Definition 


Value Mnemonic 


IE.ADP Part of DPB out of user's 


addressing space 


+LOZ oo IE.SDP Invalid DIC or DPB size 
+301 -l IE.BAD Bad parameters 
| +302 | -2 Te LES Invalid I/O function code 
| +303 | -3 IE.DNR Device not ready 
+306 -6 IE.SPC Illegal buffer 
+315 -15 IE.ABO Request aborted 
+316 -16 IE.PRI Privilege violation 
+317 cat at IE.RSU Resource in use 
£3.19 -19 LE.BYT Buffer address or length is 
odd 
+321 =21 IE.MOD | Illegal module number 
| +322 -22 ITE.CON | Another task already 
connected to interrupts | 
ITE.NOD Insufficient dynamic memory 
to allocate secondary control 


block 


IE.NLK Task not linked to interrupts 


IE.FLN ICR11 already off line 


IE.NST Task is not installed 


IE. IEF Invalid event flag number 


18.4.3 Optional Arguments 


The calling sequences discussed in subsequent sections frequently 
contain optional arguments. These arguments are enclosed in square 
brackets within the calling sequence description. A statement 
containing such arguments may be written with these parameters deleted 
by truncating the argument list if the optional parameters are at the 
end of the calling sequence, or by replacing them with commas if they 
are embedded elsewhere in the list. Consider the routine XYZ below 
having two optional arguments: 


CALL XYZ(ibuf [,ilen] [,ival]) 
If the argument ival is to be omitted, the calling sequence would be: 


CALL XYZ(IBUF,ILEN) 
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When an optional argument in the middle of the list is to be omitted, 
it is replaced with a comma. Consider the routine XYZ, above. The 
following statement is used to omit the parameter ilen: 


CALL XYZ (IBUF,,IVAL) 


NOTE 
In some subroutines, lun -- the logical 
unit number -- is indicated to be an 


optional argument. It is optional only 
if one of the Assign LUN subroutines has 
been called (ASICLN, ASUDLN, ASISLN). 
Otherwise, the lun argument is 
mandatory. 


18.4.4 Assigning Default Logical and Physical Units for Input and 
Output - ASICLN/ASUDLN (ICS/ICR) and ASISLN (DSS/DRS) 

The following subroutines must be called to assign and record a 

default LUN and physical unit if either parameter is to be unspecified 

in subsequent FORTRAN calls for which these parameters are optional. 


Calling Sequence: 

CALL ASICLN([lun] [,idsw] [,iunt]) 

CALL ASUDLN([lun] [,idsw] [,iunt]) 

CALL ASISLN(lun[,idsw] [,iunt] ) 
Before a task can issue the call to ASUDLN, the ASN command must be 
issued through MCR to assign logical device UDnn to the appropriate 
physical ICS/ICR unit. 


Argument Description: 


lun - An integer variable whose value is the number of the LUN 
to be assigned to the physical unit specified by iunt or 
unit 0. If unspecified, no LUN is assigned. The lun 


argument is mandatory for ASISLN (used for DRS11 only). 


idsw - An optional integer variable to receive the result of 
the assign lun directive. 


iunt - An optional integer variable that specifies the unit 
number to be assigned. Assumed to be 0 if omitted. 


Return Status: 
The following values are returned to idsw: 


+1 - Assignment or function successfully completed. 


-5 


LUN usage is interlocked because LUN is assigned to a 
device that is attached to another device, or a file is 
currently open on the LUN. 


-96 - Invalid LUN. 


The call to ASUDLN assigns a LUN to logical device UD: and is 
provided for compatibility with existing UDC1l software. The call to 
ASICLN assigns a LUN to device IC:. The call to ASISLN assigns a_ LUN 
to device IS:. 
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Upon successful issuance of the Assign LUN directive, the subroutine 
executes a Get LUN Information directive to obtain the actual unit 
numbers to be saved. It is therefore possible to alter the default 
physical unit referenced in a direct access call, by means of the ASN 
MCR function, provided that such logical assignments are done before 
the task is made active. 


Examples: 
1. Assign LUN 5 to ICR unit 3. 


CALL ASICLN (5,IERR,3) 
IF(IERR) 20,10,10 
10° seessdseeeseee 


2. Assign LUN 1 to logical device UD:, unit 0 


a. The following MCR command is issued to create logical 
device UDO:, and assign all references to physical device 
POLS. 


>ASN ICl: = UD: 
b. The FORTRAN call 
CALL ASUDLN (1) 


assigns logical device UDO: to LUN l. Because of the 
previous ASN command, the Executive will assign this LUN 
to physical device ICl: and return a value of 1 for’ the 
unit number in response to the GET LUN Information 
directive. This value will be stored and later 
referenced whenever the physical unit number is 
unspecified in any of the FORTRAN calls that reference 

the I/O page directly. 


3. Assign LUN 6 to logical device IS:, unit 2. 


CALL ASISLN(6,,2) 


18.4.5 Analog Input 
The following routines provide the capability of performing A/D input: 


AIRD/AIRDW - ISA Standard call to read multiple channels in 
random order. This call requires one or more 
control variables containing A/D channel and _ gain 
in the format shown in Table 18-5 (Section 18.3.2). 


AISQ/AISQW - ISA Standard call to read multiple channels in 
sequential order. 


18.4.5.1 AIRD/AIRDW: Analog Input - Specified Channel Sequence - The 
ISA standard call provides the capability of reading multiple A/D 
channels in a specified sequence. 
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Calling Sequence: 
CALL AIRD(inm,icont,idata[,isb],lun) 
or 


CALL AIRDW(inm,icont,...etc.) 


Argument Descriptions: 


inm - Integer variable specifying the number of channels to 
be read. 
icont - An integer array of size inm containing control data in 


the format shown in Table 18-5 (Section 18.3.2). 


idat ~- An integer array of dimension inm to receive’ the 
converted values. Each element in the array is paired 
with a control element in icont that defines’ the 
channel and gain. 
isb - An optional 2-word integer array to receive the results 
of the call as follows: 
+1 - Conversion successfully completed. The 
second word contains the number of channels 
converted. 
+3 - Number of channels requested was 0. 
+4 - Insufficient dynamic storage to allocate 
I/O packet. 
+8 - LUN was not assigned. 
+99 - Invalid LUN. 
+301 - At least one invalid control word was 
specified. The second I/O status word 
contains the number of channels 
successfully converted. 
+303 - Device not ready. Interrupt response was 
not received from an A/D channel within one 
second after initiation. The second word 
of I/O status contains the number of 
channels successfully converted. 
+306 - Control or data buffer not wholly within 
the user's addressing space. 
+319 - Control or data buffer is byte aligned. 
lun - An integer variable specifying the ICS/ICR logical unit 
number. This parameter is required. 
Example: 


The following example illustrates how A/D throughput can be increased 


when several IAD-IA A/D Converters are in a_e system. This is 
accomplished by means of interleaved samples that initiate parallel 
converSions on each module. Samples are to be obtained from 12 


channels on 3 IAD-IA A/D converter modules at a gain of l. 


gaANAANANAAANNAANAANANANANAAANANANAANAANANANAANAANANAAANAANAANAANAANNAANNAAANAN 


aaAA aaAaA 


aqaaaN 


aAaAN 
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PROGRAM TO SAMPLE 12 A/D CHANNELS 
IN RANDOM SEQUENCE FOR MAXIMUM 
THRUPUT. 


CHANNELS TO BE SAMPLED: 


0 
1 -A/D MODULE 0 
2 

121 -A/D MODULE 1 


241 -A/D MODULE 2 
242 
243 


INTERLEAVED SEQUENCE FOR MAXIMUM 
THRUPUT. 


0 
120 
240 

1 
121 
241 

2 
122 
242 

3 
123 
243 


THE FORTRAN CONVENTION FOR ARRAY 
STORAGE CAN BE USED TO REPRESENT 

THE ABOVE SEQUENCE IN AN N X I INTEGER 
CONTROL ARRAY. WHERE: 


NUMBER OF MODULES TO BE SAMPLED 
NUMBER OF SAMPLES PER/MODULE 


N 

I 
ALLOCATE STORAGE FOR CONTROL ARRAY 

DIMENSION ICONT (3,4) 
INITIALIZE CONTROL ARRAY FOR IAD-IA MODULE 0 

DATA ICONT(1,1),ICONT(1,2) ,ICONT(1,3) ,ICONT(1,4)/0,1,2,3/ 
INITIALIZE CONTROL ARRAY FOR IAD-IA MODULE 1 

DATA ICONT(2,1),ICONT(2,2) , ICONT(2,3) , ICONT(2,4)/120,121,122,123/ 
INITIALIZE CONTROL ARRAY FOR IAD-IA MODULE 2 

DATA ICONT(3,1),ICONT(3,2) , ICONT(3,3) , ICONT(3,4)/240, 241,242, 243/ 
ALLOCATE STORAGE FOR DATA ARRAY 


IN SIMILAR FASHION TO FACILITATE 
CHANNEL REFERENCES 
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Cc 
DIMENSION IDATA (3,4) 

Cc 

Cc BEGIN EXECUTABLE STATEMENTS 

Cc 

Cc 

C INITIATE A/D SYNCHRONOUS CONVERSION ON LUN 3 
Cc 


CALL AIRDW(12,ICONT,IDATA, ,3) 


18.4.5.2 AISQ/AISQW: Analog Input - Sequential Channel Sequence - The 
ISA standard call described below provides the capability of sampling 
multiple A/D channels in sequential order. Channels are sampled in 
increments of one, beginning with the channel specified in icont(l). 
Calling Sequence: 

CALL AISQ(inm,icont,idata [,isb],lun) 


or 


CALL AISQW(inm,icont...etc.) 


Argument Descriptions: 


inm - Integer variable specifying the number of elements’ to 
be read. 
icont - An integer array of size inm containing initial channel 


in the first element only, and gain in the format shown 
in Table 18-5 in the remaining elements. 


idat 


An integer array of size inm to receive the converted 
values. Each element is paired with the corresponding 
control element in icont that defines the gain 
parameter. 


Channels are sampled sequentially starting with the 
first channel specified in element 1 of icont. 


isb - An optional 2-word integer array to receive the results 
of the call as follows: 


+1 - Conversion successfully completed. The 
second word contains the number of channels 
converted. 


+3 - Number of channels requested was 0. 


+4 - Insufficient dynamic storage to allocate 
I/O packet. 


+8 - LUN was not assigned. 


+99 - Invalid LUN. 
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+301 At least one invalid control word was 
specified. The second I/O status word 
contains the number of channels 


successfully converted. 


+303 


Device not ready. Interrupt response was 
not received from an A/D channel within one 
second after initiation. The second word 
of I/O status contains the number of 
channels successfully converted. 


+306 


Control or data buffer is not wholly within 
the user's addressing space. 


+319 - Control or data buffer is byte aligned. 
lun - An integer variable containing the logical unit number. 
This parameter is required. 
Example: 
The following example illustrates the procedure for sequential 


sampling. Five channels are converted at gains of l, 2, 20, 50, and 
1000, starting at channel 3. 


ALLOCATE SPACE FOR STATUS ARRAY 
DIMENSION ISB (2) 


ALLOCATE SPACE FOR CONTROL ARRAY 
AND ESTABLISH INITIAL VALUES 


aaAAN aaa 


DIMENSION ICONT(5) 
DATA ICONT(1) , ICONT(2) , ICONT(3) /0000003,0010000,0050000/ 
DATA ICONT(4) , ICONT(5) /0100000,0150000/ 


ALLOCATE SPACE FOR DATA ARRAY 


AAA 


DIMENSION IDAT (5) 


Cc 
C INITIATE SEQUENTIAL, ASYNCHRONOUS CONVERSION 
C VIA LUN 1 
Cc 
CALL AISQ(5,ICONT, IDAT,ISB,1) 
10 IF(ISB(1).NE.0) GO TO 20 
(continue processing) 
Cc 
C TEST CONVERSION STATUS 
Cc 
GO TO 10 
20 (test for errors or process converted data) 
END 


18-43 


INDUSTRIAL CONTROL SUBSYSTEMS 


18.4.6 AO/AOW: Analog Output - Multichannel 


This ISA standard routine is called to output voltage from multiple 
D/A channels. 


Calling Sequence: 
CALL AO(inm,icnt,idat[,isb] [,lun] ) 
or 


CALL AOW(inm,icnt...and so forth) 


Argument Descriptions: 


inm - Integer variable containing the number of channels’ to 
be output. 

icnt - Integer array containing the channel numbers to receive 
output. 

idat - Integer array containing the output voltage setting as 


a value between 0 and 1023 where: 
0 = 0 volts de and 
1023 = +9.99 volts (full scale). 
isb - Optional 2-word integer array to receive status. One 


of the following values is returned in isb(l). The 
second element is always 0. 


+] - Function successfully completed. 
+3 - No channels requested. 
+4 - Insufficient dynamic storage to allocate an 


I/O packet. 


+8 - LUN was not assigned. 
+99 - Invalid LUN. 
+303 - Controller not ready. 
+321 - Nonexistent channel specified. 
lun - Integer variable containing the logical unit number. 


Example: 


Output the variable voltages contained in IV(l) and IV(2) to D/A 
channels 2 and 3, respectively. 
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ALLOCATE DATA ARRAY 


AAA 


DIMENSION IV(2) 


ALLOCATE CONTROL ARRAY 


aAaaANQ 


DIMENSION ICNT(2) 


ALLOCATE STATUS ARRAY 


AaAN 


DIMENSION ISB(2) 


INITIALIZE CONTROL ARRAY 


aaAN 


DATA ICNT(1) ,ICNT(2)/2,3/ 


PERFORM A/D OUTPUT VIA LUN 3 


AAD 


CALL AOW(2,ICNT,IV,ISB,3) 
IF (ISB(1).GE.3) go to error processor 


18.4.7 DOL/DOLW: Digital Output - Bistable Multiple Fields 


The following ISA standard call provides the capability of latching or 
unlatching multiple 16-point bistable digital output fields. 


Calling Sequence: 
CALL DOL(inm,icnt,idat,imsk[,isb][,lun]) 
or 


CALL DOLW(inm,icnt...and so forth) 


Argument Descriptions: 


inm ~ Integer variable specifying the number of fields to be 
latched or unlatched. 


icnt - Integer array containing the initial point within each 
field. 
idat - Integer array containing binary data that defines 


points within the field to be latched, or unlatched. 
The state of each bit is interpreted as follows: 


Ai 


Latch point 


0 Unlatch point 
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imsk - 


isb ~ 


lun - 


Example: 
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Integer array containing binary data that defines 
points within the field for which a change of state is 
permitted. 


A bit set to 1 defines a point that may assume the 
state defined by the corresponding bit in idat. A 0 
bit specifies a point for which no change of state is 
permitted. 


Optional 2-word integer array to receive the results of 
the call. Status is returned in isb(l) as shown below. 
isb(2) is always 0. 


+1 - Function successfully completed. 

+3 - No points specified. 

+4 - Insufficient dynamic storage to allocate an 
I/O packet. 

+8 - LUN was not assigned. 

+99 - Invalid LUN. 

+303 - Controller not ready. 

+321 - Nonexistent point number specified. One or 


more points within the field do not exist. 


Integer specifying the Logical Unit Number. 


Reset points 0,1,20 and 21 


QAaAN 


QARQAANA 


aAaaAAN 


DIMENSION ICNT(2) ,IDAT(2) ,IMSK(2) 


INITIALIZE THE CONTROL ARRAY 


DATA ICNT(1),ICNT(2)/0,20/ 


INITIALIZE MASK ARRAY TO EFFECT A 
CHANGE-OF-STATE ONLY ON THE SPECIFIED 


POINTS. 


DATA IMSK(1) ,IMSK(2) /0000003,0000003/ 


RESET THE SPECIFIED POINTS. ICR IS ASSIGNED 
TO LUN 3. 


CALL DOLW(2,ICNT,IDAT, IMSK,,3) 
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18.4.8 Digital Input 

Both of the following subroutines perform their functions’ through 

direct access to the ICS/ICR hardware registers. Therefore, the 

physical unit number replaces LUN in the calling sequences described 

below. Note that any need for conversion of BCD encoded digital input 

into binary can be accomplished through the FORTRAN function 
IBIN=KBCD2B (IBCD). 

Binary data can be converted to BCD through the FORTRAN function. 
IBCD=KB2BCD (IBIN). 


The maximum input value for conversion is 9999. 


NOTE 
When the physical unit number is 
explicitly included in the calling 


sequence, it cannot be reassigned by the 
MCR command ASN. 


18.4.8.1 DI/DIW: Digital Input - Digital Sense Multiple Fields - This 
ISA standard subroutine provides the capability of reading multiple 
16-point digital sense fields. 
Calling Sequence: 

CALL DI(inm,icnt,idat[{,isb][,iun]) 


or 


CALL DIW(inm,icnt...and so forth) 


Argument Descriptions: 


inm - Integer variable specifying the number of fields to be 
‘ read. 
icnt - Integer array containing the initial point number of 


each field. 


idat - Integer array to receive the input data. 
isb - Optional, 2-word integer array to receive the results 
of the call. The status is returned in isb (1) as 
follows: 
+1 - Function succesfully completed. 
+3 - No points requested. 
+321 - Nonexistent point requested. One or more 
points within the 16-bit field does not 
exist. 
iun - Optional integer variable specifying the physical unit 
number. 
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Example: 


Read two contact sense fields starting at points 3 and 27 on physical 
unit IC2?.4 


DIMENSION ICNT(2), IDAT(2) ,ISB(2) 
DATA ICNT(1),ICNT(2)/3,27/ 


CALL DI (2,ICNT,IDAT,ISB, 2) 
IF (ISB(1).GE.3) go to error procedure 


18.4.8.2 RCIPT: Digital Input - Digital Interrupt Single-Point - The 
following subroutine returns the state of a single digital interrupt 
point as a logical value. 

Calling Sequence: 


CALL RCIPT (ipt,isb[,iun]) 


Argument Descriptions: 
ipt - Integer variable defining the point to be read. 


isb - a 2-word integer array to receive status and data as 
follows. Status is returned to isb(l). 


+1 - Function successfully completed. Data is 
returned to isb(2) as a logical value, 
where: 


-TRUE. (-1) Point closed. 


- FALSE. (0) Point open. 


+321 - Nonexistent point specified. 
iun - Optional integer variable defining the physical unit 
number. 


Example: 
Read the state of contact interrupt point 3 on unit 0. 


DIMENSION ISB (2) 


CALL RCIPT (3,1ISB,0) 
IF (ISB(2).EQ..FALSE.) go to point open routine. 
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18.4.9 DOM/DOMW: Digital Output Momentary - Multiple Fields 


This ISA standard call allows multiple 16-bit fields to be pulsed. 


Calling Sequence: 


CALL DOM 


or 


(inm,;icnt,idat[ ,idx] [T,isb] [;1un] ) 


CALL DOMW (inm,icnt...and so forth) 


Argument Descriptions: 


inm 


icnt 


idat 


idx 


isb 


lun 


Example: 


Integer variable specifying the number of fields to be 
pulsed. 


Integer array containing the initial point in each 
field. 


Integer array defining the points to be pulsed. A bit 
is set corresponding to each point that is to be 
triggered. 


Optional dummy integer variable retained for 
compatibility with the standard form of the call. 


Optional 2-word integer array to receive the results of 
the call as follows in isb(1), isb(2) is set to 0. 


+2 - Number of fields to be output is 0. 


+4 - Insufficient dynamic storage to allocate on 
I/O packet. 


+8 - LUN not assigned. 
+99 - Invalid LUN. 
+303 - Controller not ready 


+321 


Nonexistent point specified. One or more 
points within a field do not exist. 


Integer variable defining the logical unit number. 


Pulse momentary digital output fields defined by points 20, 37, and 0 


on LUN 1. 


DIMENSION ICONT(3),IDAT(3) 


DATA ICONT(1) ,ICONT(2) , ICONT(3)/20,37,0/ 


CALL DOM(3,ICONT,IDAT,,1) 
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18.4.10 RTO/RTOW: Remote Terminal Output 
The following function provides the capability of transmitting a 
character string to a remote ICRI11 terminal. Both synchronous and 
asynchronous forms are supported. 
Calling Sequence: 

CALL RTO (ibc,idat[,isb][,lun]) 


or 


CALL RTOW (ibc,idat....etc.) 


Argument Descriptions: 


ibe - Integer variable specifying the number of bytes. to 
output. 
idat - Byte array (LOGICAL * a) containing the character 


string to be output. 


isb - Optional, 2-word integer array to receive the results 
of the call in isb(1) as follows. isb(2) is set to the 
number of bytes actually transferred to the device. 


0 - Operation pending. 

+1 - Function successfully completed. 

+3 - No bytes to be transmitted. 

+4 - Insufficient dynamic storage to allocate 


I/O packet. 


+8 - Unassigned LUN. 
+99 - Invalid LUN. 
+303 - Device not ready. Terminal failed to 


respond within 1 second after character was 
transmitted. 


+306 - Part or all of buffer is out of the issuing 
task's addressing space. 


+321 - Nonexistent module. Device is ICS1l. 


lun - Integer variable defining the logical unit number. 


Example: 


Output a character string to a remote terminal by the ICR unit 
assigned to LUN 3. 


CALL RTOW(32,'APPLY +5 VOLTS TO A/D CHANNEL 10',,3) 


INDUSTRIAL CONTROL SUBSYSTEMS 


18.4.11 Unsolicited Interrupt Data - Continual Monitoring 


Subroutines are provided that permit a FORTRAN program to continually 
monitor unsolicited interrupt data supplied to a user circular buffer, 
as described in Section 18.3.6. Such routines allow the program to 
connect a buffer for input, disconnect the buffer upon completion, and 
read and return the buffer contents in a format suitable for FORTRAN 
processing. The calls summarized below perform these functions for 
interrupting digital input modules, counters, and remote terminal 
inputs: 


Interrupting Digital Inputs 


CTDI - Connect a buffer to receive digital interrupts 

RDDI - Read the state of a single interrupting point 

RDCS - Read the state of a single interrupting point for which 
a change of state has been detected 

RDWD ~ Read 16 bits of interrupt data from the circular buffer 

DFDI - Disconnect a buffer from digital interrupts 


Counter Modules 


CTTT - Connect a buffer to receive counter interrupts 
RDTI - Read the counter circular buffer 
DFTI - Disconnect a buffer from counter interrupts 


Remote Terminal Input 


Cory - Connect a buffer to receive remote terminal inputs 
RDTY - Read remote terminal data from the circular buffer 
DFTY - Disconnect a buffer from remote terminal interrupts 


18.4.11.1 CTDI: Connect a Buffer for Receiving Digital Interrupt Data 
- The following routine allows a task to provide a circular buffer 
that will receive digital interrupt data, and to define an event flag 

that will be set upon the occurrence of each interrupt. 

Calling Sequence: 


CALL CTDI (ibuf,isz,iev[,isb] [,lun]) 


Argument Descriptions: 


ibuf - An integer array making up the circular buffer that is 
to receive interrupt data. 


iSz - Integer variabie specifying the length of the circular 
buffer in words. 
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iev - Integer variable specifying the event flag that is to 
be set whenever the driver receives an interrupt from a 
digital input module. 


isb - Optional, 2-word integer array to receive the results 
of the call. The status values specified below are 
returned to isb(l). 


+] - Function successfully completed. isb (2) 
receives the number of words passed per 
interrupt in the low byte. 


+4 - Insufficient dynamic storage to allocate an 
T/O packet. 


+8 - Unassigned LUN. 

+99 - Invalid LUN. 

+306 - Part of buffer is out of the user's address 
space or buffer is too small to accommodate 


a Single entry. 


+316 - Privilege violation - task is check- 
pointable and not fixed in memory. 


+319 - Buffer address or length is an odd number 
of bytes. 
+322 - Another task is already connected to 


interrupts. 
+397 - Invalid event flag specified. 
lun - Integer variable specifying the logical unit number. 


The space allocated for the circular buffer must be large enough to 
accommodate at least one 5-word entry plus an additional 10 words of 
storage that are required by the subroutines that read circular buffer 
contents. Thus, the buffer allocation specified by the integer 
variable isz may be computed as 


isz = (10 + 5 * n) 


The number of entries to be contained in the buffer. 


isz 


Expressed in words. 


18.4.11.2 Reading Digital Interrupt Data - Each of the following 
routines reads data that has been stored in the circular buffer and 
performs the following common processing: 

i. Detects, and optionally reports, the occurrence of an error 
entry that has been placed in the buffer by the driver 
because of a nonrecoverable device fault (for example, fatal 
serial line error or remote power-fail). 
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Clears the trigger event flag when no further entries remain 
to be processed. 


Clears and optionally reports any overrun conditions. 


of the following three routines can be invoked by a_= single 


RDDI: Read Digital Interrupt Data from a Circular Buffer 


The RDDI FORTRAN subroutine reads contact interrupt data from 
a circular buffer that was specified in a CTDI call (see 
18.4.11.1). It does no actual input or output, but rather 
performs a point-by-point scan of an interrupt entry in the 
buffer, returning the state of each point as a logical value. 


On the initial call to RDDI, the module number and data of 
the next interrupt entry are read from the circular buffer 
and stored for subsequent reference. The subroutine’ then 
sets the current data bit number n to 0, examines the state 
of data bit n, and converts bit n to a point number by the 
following formula: 


ipt = module number * 16 +n 


On each subsequent call, n is incremented by one and_ then 
data-bit n iS examined in the stored module data. Whenn 
reaches 16, it is reset to 0 and an attempt is made to read 
the next interrupt entry from the circular buffer. If a 
valid entry is not found, ipt is set negative and ict (if 
specified) is either assigned a value of 0 or an overrun 
count that is maintained by the ICS/ICR driver. If ict is 0, 
no further entries remain. A nonzero value indicates that 
the driver received more data than could be stored in the 
buffer, and ict represents the number of entries that were 
discarded. 


The variable ict receives the control register contents that 
are set by the driver -- as described in Section 
18.3.6 -- whenever a nonrecoverable controller error occurs. 


Calling Sequence: 


CALL: RDDI (iptyival [;ict]) 


Argument Descriptions: 


ipt - A variable to which the digital input point 
number is returned. It may be set as follows: 


1. ipt 0 if no valid entry is found 


The specific value of ipt reflects the error 
that was detected as follows: 


-l1 - no data (that is, no interrupt data 
currently in buffer) 


-2 - overrun 
-3 - hardware error 


2. ipt => 0 if the value indicated is a point 
number; the state is returned to ival. 
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ival - A variable to which the state of the point is 
returned; it may be set as follows: 
1. .FALSE. (0) if the point is open 


2 - TRUE. (-1) if the point is closed 


ict - Optional integer variable to receive the overrun 
count or the contents of the CSR register on the 
occurrence of a fatal controller error. 


Otherwise, set to 0. 


NOTE 


A task reading the circular buffer 
should not issue a Wait-For directive 
until a buffer-empty condition is 
reported. See Section 18.4.11.11 for an 
example of how to read circular-buffer 


RDCS: Read Digital Interrupt Points That Have Changed State 


The RDCS FORTRAN subroutine returns data in the format of 
subroutine RDDI -- as described above -- except that only 
points that have changed state are processed, resulting in 
Significantly improved throughput and reduced processing 
overhead for the calling task. 


Processing specific to the routine is as follows: 


On the initial call, the module number, module data, and 
change of state information are read from the circular buffer 
and stored for later reference. The subroutine then sets the 
current data bit number n to 0 and begins scanning the 
change-of-state word until a nonzero bit is found. The point 
number and current state are then reported as previously 
described. If no change of state is found or when no further 
bits remain to be processed, the next entry is fetched as 
described above. 


The processing of error conditions is identical to subroutine 
RDDI. 


Calling Sequence: 


CALL RDCS (ipt,ival[,ict]) 


Argument Descriptions: 


ipt - Integer variable to receive the digital input 
point number. It may be set as follows: 


1. aipt 0 if no valid entry is found (that is, 
overrun, error, or no data in buffer). The 
specific value of ipt reflects the error 
that was detected as follows: 


-l - no data 
-2 - overrun 
-3 - hardware error 
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2. ipt => 0 if the value indicated is a point 
number, the state is returned to ival. 


ival - Integer variable to receive the state of the 
point as a logical value where: 


1. .FALSE. (0) = Point open 
2. .TRUE. (-1) = Point closed 


neg w - Optional integer variable. A nonzero value 
indicates that the variable has been set with an 
overrun count returned by the driver, or with 
the contents of the CSR register on the 
occurrence of a fatal controller error. 
Otherwise, set to 0. 


NOTE 


A task reading the circular buffer 
should not issue a Wait-For directive 
until a buffer-empty condition is 
reported. See Section 18.4.11.11 for an 
example of how to read circular-buffer 
entries. 


RDWD: Read a Full Word of Digital Interrupt Data 

The following subroutine is called to return a full word of 
digital interrupt data from the circular buffer, and 
optionally change of state information. A new entry is” read 
for each call; hence, throughput is high when processing is 
contingent upon several possible conditions within a module. 
Calling Sequence: 


CALL RDWD (imod,ival[,ict][,icos]) 


Argument Descriptions: 


imod - Integer variable to receive the module number or 
status as follows: 


1. imod 0 if no data is present or an overrun 
condition or error was detected 


The specific value of ipt reflects the error 
that was detected as follows: 


-l - no data 
—-2 - overrun 
-3 - hardware error 


2. imod => 0 Module number. Interrupt data is 
in ival 


ival - Integer variable to receive the digital 
interrupt data. 


L8=55 


INDUSTRIAL CONTROL SUBSYSTEMS 


ict - Optional integer variable. A nonzero value 
indicates that the variable has been set with an 
overrun count returned by the driver, or with 
the contents of the CSR register on _ the 
occurrence of a fatal error. Otherwise, set to 


0. 
icos - Optional integer variable to receive 
change-of-state information. Bits set to al 


correspond to points for which a change of state 
has been recorded. 


NOTE 


A task reading the circular buffer 
should not issue a Wait-For directive 
until a buffer-empty condition is 
reported. See Section 18.4.11.11 for an 
example of how to read circular-buffer 
entries. 


18.4.11.3 DFDI: Disconnect a Buffer from Digital Interrupts - The 
following routine is called to disconnect a task's circular buffer 
from digital interrupts. 

Calling Sequence: 


CALL DFDI ([isb][,lun]) 


Argument Descriptions: 


isb - Optional 2-word integer array to receive the results of 
the call as follows. isb(2) is always 0. 


+1 - Function successfully completed 


+4 - Insufficient dynamic storage to allocate 
I/O packet. 


+8 - Unassigned LUN. 
+99 - Invalid LUN. 
+322 - Task not connected to interrupts. 


lun - Integer variable containing logical unit number. 


18.4.11.4 CTTI: Connect a Buffer for Receiving Counter Data - The 
following subroutine may be called to connect a circular buffer that 
is to receive counter data, and to define an event flag that is to be 
set upon occurrence of each interrupt. 


Calling Sequence: 


CALL CTTI (ibuf,isz,iev,iv!,isb][,lun]) 
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Argument Descriptions: 


ibuf - An integer array making up the circular buffer that is 
to receive interrupt data. 

isz - Integer variable specifying the length of the circular 
buffer in words. 

iev - Integer variable defining an event flag that is to be 
set whenever the driver receives an interrupt from a 
counter module. 

iv - Integer array of initial counter values. One element 
is required for each counter in the physical unit. The 
value is used to initialize and reset the counter when 
a value of 0 is reached. This parameter may be reset 
for a specific module through a call to SCTI. 

isb - Optional 2-word integer array to receive the results of 
the call. The status values specified below are 
returned to isb(1l). 

+1 - Function successfully completed. isb{(2) 
receives the number of words passed per 
interrupt in the low byte. 

+4 - Insufficient dynamic storage to allocate an 
I/O packet. 

+8 - Unassigned LUN. 

+99 - Invalid LUN. 

+303 - Controller not ready. 

+306 - Part of buffer is out of the user's address 
space or buffer is too small to accommodate 
a Single entry. . 

+316 - Privilege violation -- task is 
checkpointable and not fixed in memory. 

+319 - Buffer address or length is an odd number 
of bytes. 

+322 - Another task is already connected to 
interrupts. 

+397 - Invalid event flag specified. 

lun - Integer variable specifying the logical unit number. 


The space allocated for the circular buffer must be large enough to 
accommodate at least one 4-word entry plus an additional 8 words of 
Storage required by the subroutine that reads buffer contents (RDTI). 
The buffer allocation specified by the variable isz may be computed as 


isz = (8 + 4 * n) 


The number of entries to be contained in the buffer. 
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NOTE 


A task reading the circular buffer 
should not issue a Wait-For directive 
until a buffer-empty condition is 
reported. See Section 18.4.11.11 for an 
example of how to read circular-buffer 
entries. 


18.4.11.5 RDTI: Read Counter Data from the Circular Buffer - The 
following call returns counter interrupt data from the circular 
buffer. A new entry is read on each call. 

Calling Sequence: 


CALL RDTI (imod,ivalf,ict]) 


Argument Descriptions: 


imod - Integer variable to receive module number and status as 
follows: 


1. imod 0 No data in buffer, data overrun or error 
condition detected The specific value of ipt 
reflects the error that was detected as follows: 


-l - no data 
-2 - overrun 
-3 - hardware error 


2. imod => 0 Module number of counter. Interrupt data 
is in ival. 
ival - Integer variable to receive the counter data at 


interrupt. 


Ice - Optional integer variable to receive the overrun count, 
or the ICSR contents returned by the driver on the 
occurrence of a fatal hardware error. Otherwise, set 
to 0. 


NOTE 
A task reading the circular buffer should not 
issue a Wait-For directive until a buffer-empty 
condition is reported. See Section 18.4.11.11 


for an example of how to read circular-buffer 
entries. 


18.4.11.6 Miscellaneous Counter Routines 
1. RSTI: Read a Counter Module 


The foiiowing routine directiy accesses a counter register to 
return its current value. 
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Calling Sequence: 


CALL RSTI (imod,isb[,iun] ) 


Argument Descriptions: 


imod ~ An integer variable containing the number of the 
counter to be read. 


isb - A 2-word integer array to receive status. and 
data as follows. Status is returned to isb(l). 


+1 - Function successfully completed. 
Data is returned to isb(2). 


+321 - Nonexistent module specified. 


iun - Optional integer variable specifying the ICS/ICR 
physical unit number. 


2. SCTI: Reset a Counter Initial Value 


The following routine may be called by any task to revise the 
initial value that is used to activate a counter. 


Calling Sequence: 


CALL SCTI (imod,ival{,isb][,lun]) 


Argument Descriptions: 


imod - Integer variable specifying the relative module 
number of the counter to be reset. 


ival - Integer value specifying the new initial value. 


isb - Optional 2-word integer array to receive status 
as follows. isb(2) is always 0. 


+1 - Function successfully completed 


+4 - Insufficient dynamic storage to 
allocate an I/O packet 


+8 - Unassigned LUN 

+99 - Invalid LUN 

+303 - Controller not ready 

+321 - Nonexistent module specified 
lun - Integer specifying the logical unit number. 


18.4.11.7 DFTI: Disconnect a Buffer from Counter Interrupts - The 
following subroutine is calied to disconnect the task's circular 
buffer from interrupts. 


Calling Sequence: 


CALL DFTI ([isb][,lun] ) 
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Argument Descriptions: 


isb - Optional 2-word integer array to receive status as 
follows. isb(2) is always 0. 


+1 - Function successfully completed. 
+4 - Insufficient dynamic storage to allocate an 
I/O packet. 
+8 - Unassigned LUN. 
+29 - Invalid LUN. 
+322 - Task was not connected to interrupts. 
lun - Integer variable specifying the logical unit number. 


18.4.11.8 CTTY: Connect a Circular Buffer to Terminal Interrupts - The 
following routine allows a task to provide a circular buffer to 
receive remote terminal input data, and to define an event flag that 
is set on the occurrence of each interrupt. 

Calling Sequence: 


CALL. CTTY: -(ibut,isz,2ev(>i7sbi.¢ lun) 


Argument Descriptions: 


The following arguments are identical in form and function to those 
described for subroutine CTDI (see Section 18.4.11.1): 


ibuf - An integer array making up the circular buffer that 
receives interrupt data 


isz - Length of the circular buffer in words 
iev - Event flag to be set on each terminal interruot 
Buffer size is computed as 


isz = (8 + 4 * n) 


The number of entries that can be stored in the buffer. 


isb - Optional 2-word integer array to receive the results of 
the call. The status values specified below are 
returned to isb(l). 


+1 - Function successfully completed. isb(2) 
receives the number of words passed per 
interrupt in the low byte. 


ae : 
+4 - Insufficient dynamic 


I/O packet. 


n~ ATITAAAYK mn 
Vv ast.itSCace all 


+8 - Unassigned LUN. 


+99 - Invalid LUN. 
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+306 - Part of buffer is out of the user's address 
space or buffer is too small to accommodate 
a Single entry. 

+316 - Privilege violation -- task is 
checkpointable and not fixed in memory. 

+319 - Buffer address not on a word boundary or 
length is an odd number of bytes. 

+321 - Nonexistent module specified. Unit is 
TCS iil 

+322 - Another task is already connected to 
interrupt. 

+397 - Invalid event flag specified. 

lun - Logical unit number. 


18.4.11.9 RDTY: Read a Character from the Terminal Buffer - This 


subroutine retrieves ae_e single 


buffer on each call. 
Calling Sequence: 


CALL RDTY (ind,ichr[,i 


Argument Descriptions: 


sadip| 


ind - An integer variable to receive status as follows: 


1. =0 character retrieved from buffer is in ichr 


2. <0 no data in buffer, overrun, or hardware error 


The specific value of ind reflects the error 
was detected as follows: 


=e 
ma 

a 

ichr - Logical * 1 
data. Te 


will be set. 


no data 
overrun 
hardware error 


character from the terminal circular 


that 


or integer variable to receive the terminal 
an integer is specified, only the low byte 


ivr - Optional integer variable to receive the overrun count, 
or the ICSR contents on the occurrence of a fatal 
hardware error. Otherwise, set to 0. 


NOTE 


A task reading the circular buffer should not 


issue a Wait-For directive until a buffer-empty 


condition is reported. See Section 18.4.11.11 


for an 
entries. 


example of how to read circular-buffer 
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18.4.11.10 DFTY: Disconnect a Circular Buffer from Terminal Input - 
The following routine disconnects a task's circular buffer from 
terminal inputs. 
Calling Sequence: 


CALL DFTY (fisb][,lun]) 


Argument Descriptions: 


isb - Optional, 2-word integer array to receive status in 
isb(1) as follows. isb(2) is always set to 0. 


+1 - Function successfully completed. 


+4 - Insufficient dynamic storage to allocate an 
I/O packet. 


+8 - Unassigned LUN. 

+99 - Invalid LUN. 

+322 - Task was not connected to interrupts. 
lun - An integer specifying the logical unit number. 


18.4.11.11 Programming Example - The following are excerpts from a 
FORTRAN program that is to monitor a remote terminal for input and 
echo the received characters when a carriage return is detected. 


C 
C SPECIFY BYTE FORMAT FOR TERMINAL DATA 
C 

LOGICAL*1 TCHR 


ALLOCATE STORAGE FOR THE TERMINAL 
BUFFER 


QAaAaAaAN 


DIMENSION IBUF(32) 


ALLOCATE STORAGE FOR THE PACKED 
INPUT DATA SO THAT IT IS ALIGNED 
ON A WORD BOUNDARY 


AAAAN 


DIMENSION ICHR(40) 
DIMENSION TCHR(80) 
EQUIVALENCE (TCHR, ICHR) 


ALLOCATE STORAGE FOR A 
2-WORD STATUS BLOCK 


AAAN 


DIMENSION ISB(2) 


INITIALIZE ICR11 LOGICAL UNIT(7) AND 
TRIGGER EVENT FLAG NUMBER (2) 


aaana 


DATA IEV, LUN/2, 7/ 


AAaAAA 


AAAAARAANA 
j=) 


jo) 


AANAAWAAARAANAANINS 
jo) 


NDAQAAAA 
j=) 


fon) 


aAaaANsI 


aaa 
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CONNECT THE TASK TO TERMINAL 
INPUTS. IF CONNECT FAILS--STOP 1 


CALL CTTY (IBUF,32,IEV,ISB,LUN) 
IF (ISB(1).GE.3) STOP 1 


10--POLL THE CIRCULAR BUFFER 
FOR DATA. ECHO THE LINE WHEN 
80 CHARACTERS ARE RECEIVED 
OR A CARRIAGE RETURN IS 
DETECTED. 

DO 70 I = 1,80 

20--WAIT FOR TRIGGER EVENT FLAG 

CALL WAITFR (IEV) 


30--PACK THE CIRCULAR BUFFER DATA 
INTO THE BYTE ARRAY 


CALL RDTY (ISB,TCHR(I), IVR) 
DISPATCH ON ERROR CONDITION 


GO TO (20,50,40)-ISB 
GO TO 60 


40--REPORT HARDWARE FAULT 


CALL ALARM (IVR) 


GO TO 30 
50--REPORT OVERRUN CONDITION 


CALL LOST (IVR) 


GO TO 30 

60--CHECK FOR CARRIAGE RETURN, 
EXIT TO ECHO ROUTINE IF 
PRESENT 

IF (TCHR(I).EQ."15) GO TO 80 

CONTINUE 

80--FALL THROUGH TO ECHO A LINE 

CALL RTOW (I,TCHR,,LUN) 

DISCONNECT TERMINAL BUFFER, EXIT 

CALL DFTY (,LUN) 


CALL EXIT 
END 
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The procedure for reading the buffer in the example above may be 
summarized as follows: 


1. Wait for the trigger event flag specified in the call to 
connect the buffer. 


2. Upon regaining control, call the appropriate routine to read 
the buffer until one of the following terminal conditions is 
detected: 


a. All data has been read. 
b. An overrun count is detected. 


c. A fatal error is encountered. 


3. On the occurrence of 2a or 2b, perform any appropriate 
processing; then return to scan for additional data. 


4. If a hardware error is detected, use the ICSR_ register 
contents for further fault analysis and warning as 
appropriate. In the event of such an error, the event flag 
will not be set by the driver again unless normal service is 
resumed. 


5. A calling task should not execute the Wait-For directive 
until a buffer-empty condition is detected. This is because 
the user's buffer pointer is advanced after detecting and 
clearing an overrun condition, and the trigger-event flag is 
cleared only when a buffer-empty condition is detected. 


18.4.12 Unsolicited Interrupt Processing - Task Activation 
The following routines provide the capability of linking a task to an 


interrupt, soliciting information from the driver concerning how the 
task was activated, and unlinking a task from all interrupts. 


18.4.12.1 LNK: Link a Task to Interrupts - This subroutine allows 
any installed task to be activated on the occurrence of any 
unsolicited interrupt. 

Calling Sequence: 


CALL LNK (tnam,iprm[,isb][,lun]) 
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Argument Descriptions: 


tnam - Real variable containing task name in  RADIX-50 
format. 
iprm - A 5-word integer array containing the following 
data: 
iprm(1l) - Interrupt class. May be one of the following: 
0 - Digital interrupts 
1 - Counters 
2 - Remote terminal (CTRL/C only) 
3 - Error interrupts 
iprm(2) - Reserved. 
iprm(3) - Optional event flag set if task to be activated is 
not dormant when the interrupt occurs. 
iprm(4) - Hardware-dependent parameters as follows: 
iprm(5) 
Interrupt Class Parameter Contents 
Digital iprm(4) = Point number 
iprm(5) = Change-of-state mask 
Counter iprm(4) = Module number 
iprm(5) = Counter initial value 
Remote Terminal iprm(4) = not used 
iprm(5) = not used 
Error iprm(4) = not used 
iprm(5) = not used 
isb - Optional 2-word integer array to receive status in 


isb(1) as follows. isb(2) is always set to 0. 
+1 - Function successfully completed. 


+3 - Unrecognized interrupt class 
specified. 


+4 - Insufficient dynamic storage to 
allocate I/O packet. 


+8 - Unassigned LUN. 
+99 - Invalid LUN. 
+301 - Task tnam not installed. 
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lun 


Example: 


INDUSTRIAL 


+303 


+317 


+323 


+380 


+397 


CONTROL SUBSYSTEMS 


Controller not ready. 


Resource in use. Other task already 
linked to interrupt. 


Insufficient dynamic memory to 
allocate secondary control block. 


Task tnam not installed. 


Invalid event flag number specified. 


- Optional integer specifying the logical une 


number. 


Link task ALARM to report fatal hardware errors arising from a 
malfunction on any ICR11 physical unit. 


DIMENSION IPRM(5) 


iw 
2 
3s 


AAAARANR 


INTERRUPT CLASS 


INITIALIZE PARAMETER ARRAY WITH: 


RESERVED ELEMENT CLEARED 


GLOBAL EVENT FLAG 


DATA IPRM(1), IPRM(2), IPRM(3)/3,0,64/ 


DATA ALARM/6RALARM / 


CALL LNK (ALARM,IPRM,,7) 


18.4.12.2 RDACT: 
task to determine 


active. 


Calling Sequence: 


Read Activation Data - The following call allows a 
the interrupt conditions that caused it to become 


CALL RDACT (iprm[,isb] [,lun]) 


Argument Descriptions: 


iprm 


A 6-word integer array to receive activation data 


in the following format. 


- Activation indicator (see Section 18.3.7.5). 


- Physical unit number of ICR. 
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iprm(3) - Generic code. Set to one of the following values: 
0 ~- Remote terminal 
Lees - Digital interrupt 
4, 5) - Counter interrupt 
177770 - Fatal hardware error 
iprm(4) - Relative module number. 
iprm(5) - Hardware-dependent data. 


iprm(6) 


The following data is returned based upon the type of interrupt 
module: 


Generic 
Module Type Code Parameter Contents 
Remote Terminal 0 iprm(5) = terminal input character 
iprm(6) = undefined 
Digital Interrupt ee iprm(5) = module data 
iprm(6) = change-of-state data 
Counter 4,5,6 iprm(5) = value of the counter at 
interrupt 
iprm(6) = undefined 
Error 177770 iprm(5) = contents of ICSR 
iprm(6) = contents of ICAR. 
isb - Optional 2-word integer array to receive status in 
isb(l1) as follows. isb(2) is set to 0. 
+1 - Function successfully completed. 
+4 - Insufficient dynamic storage to allocate 
I/O packet. 
+8 - Unassigned LUN. 
+99 - Invalid LUN. 
+306 -~- iprm array not fully within the task's 
addressing space. 
+319 - Address of iprm is odd. 
+379 - Task not linked to ICS/ICR interrupts. 
lun - Integer variable specifying the logical unit number. 
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Example: 


The following is an excerpt from a program that reads activating data 
into array IACT and conditionally exits if the event flag (IEFN) 
specified in a previous link request, issued by another task, is not 
set. 


ALLOCATE SPACE FOR DATA ARRAY 


AAA 


DIMENSION IACT (6) 


10 CALL RDACT (IACT,,7) 


e 


CLOSE ALL FILES 


aaAQ 


CALL CLOSE (1) 
CALL CLOSE (2) 


EXIT IF TRIGGER EVENT FLAG IS NOT SET 
ELSE CLEAR EVENT FLAG AND RESTART. 


AAANQ 


CALL EXITIF (IEFN) 


FLAG WAS SET. CLEAR IT AND 
CONTINUE. 


aAaaAaaAN 


CALL CLREF (IEFN) 
GO TO 10 

STOP 

END 


The foregoing example illustrates the following considerations when a 
task is made active by ICS/ICR interrupts: 


1. To avoid race conditions, the Exit-If directive should be 
used to test the state of the event flag and conditionally 
exit. Issuing a Test Event Flag directive followed by an 
Exit would cause a flag set condition occurring after the 
test to go unrecognized. 


2. Use of the Exit-If directive bypasses the closure of all 
files that is normally done automatically by the FORTRAN 
object time system when the program executes a STOP or CALL 
EXIT statement. Thus, to exit cleanly, the program must 
explicitly close all files before invoking the directive. 


18.4.12.3 UNLNK: Remove Interrupt Linkage to a Task - The following 
call removes all linkage between a task and ICS/ICR interrupts. 
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Calling Sequence: 


CALL UNLNK (tnam,iprm[,isb][,lun]) 


Argument Descriptions: 
tnam - Real variable containing task name in Radix-50 format. 


iprm - Integer variable containing the interrupt class. May 
be one of the following: 


0 - Digital interrupts 
1 - Counters 

2 -~ Remote terminal 

3 - Error interrupts 


4 


All interrupts 


isb - Optional, 2-word integer array to receive the results 
of the call in isb(1) as follows. isb(2) is set to 0. 


+1 - Function successfully completed. 


+4 - Insufficient dynamic storage to allocate an 
I/O packet. 


+8 - Unassigned LUN. 
+99 - Invalid LUN. 
+379 - Task not linked to ICS/ICR interrupts. 
+380 - Task not installed. 
lun - Integer variable specifying the logical unit number. 


Example: 
Remove the linkage between task ALARM and all ICS/ICR interrupts. 
DATA ALARM/6RALARM / 


CALL UNLNK (ALARM,,,7) 


18.4.13 Maintenance Functions 
The following functions cause the ICS/ICR driver to suppress or enable 
hardware error reporting while on-line maintenance and troubleshooting 
is in progress, as described in Section 18.3.9. 

OFLIN - Place selected unit off line. 


ONLIN - Return selected unit to on-line status. 


These calls may be issued only by a privileged task. 
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18.4.13.1 OFLIN: Place Selected Unit in Offline Status - The following 
call is executed to set a controller off line: 


CALL OFLIN ([isb] [,lun]) 


Argument Descriptions: 


isb - Optional 2-word integer array to receive the results of 
the call in isb(1) as follows. isb(2) is always 0. 


+] - Function successfully completed. 


+4 - Insufficient dynamic storage to allocate an 
I/O packet. 


+8 - LUN not assigned. 
+99 - Invalid LUN. 
+316 - Issuing task not privileged. 
+380 -—- Device already off line. 
lun - Integer variable specifying the ICS/ICR logical unit 
number. 


18.4.13.2 ONLIN: Return a Device to On-line Status - The following 
call will return the selected unit to on-line status. 


CALL ONLIN ([isb] [,lun]) 


Argument Descriptions: 


isb - Optional 2-word integer array to receive the results of 
the call in isb(1) as follows. isb(2) is always 0. 


+1 - Function successfully completed. 


+4 - Insufficient dynamic storage to allocate an 
I/O packet. 


+8 - LUN not assigned. 
+99 - Invalid LUN. 
+316 - Issuing task not privileged. 
lun - Integer variable specifying the logical unit number. 


18.5 ERROR DETECTION AND RECOVERY 


Error Detection and recovery procedures encompass the following 
contingencies. 


i. Nonrecoverabie seriai iine errors 


2. Power-fail at the remote station 
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3. Power recovery at the processor 
4. No response from an interrupting module 


The first two conditions are dealt with in a manner similar to that of 
other types of unsolicited interrupts. Specifically, such occurrences 
may cause a task to be activated, and are reported to all tasks’ that 
are connected to digital, counter, or terminal input. The following 
paragraphs discuss specific driver activity relating to each error 
condition. 


18.5.1 Serial Line Errors 


The driver detects nonrecoverable serial line errors. A 
nonrecoverable error condition is defined as the occurrence of a 
predetermined number of error interrupts in an interval of 1 second, 
or no response from the controller upon initiation of an output data 
transfer by means of the serial line. The occurrence of such a 
condition causes the driver to perform as follows: 


1. Place the controller in a "not ready" status. 
2. Disable further error interrupts. 


3. Report the condition to the task that is linked to errors, 
and to any tasks connected to receive unsolicited interrupt 
data from the faulty unit. Subsequent QIO requests that 
transfer data to or from the unit are rejected with a status 
of IE.DNR. 


Requests for interrupting modules that are pending (A/D converters and 
terminal output) are allowed to time out with the error code IE.DNR. 
The serial line error rate required to consider the link inoperative 
may be specified by the user at the time of system generation. 


After reporting the error as described above, the driver will 
automatically remove the "not ready" status when the error condition 
is not detected at the end of any 1-second interval. If requested 
during system generation, the state of the following remote modules 
will be restored as described. 

1. Bistable outputs - set to last recorded state 


2. Counters - reinitialized to last initial value 


3. Analog outputs —- restored to last output value 


18.5.2 Power-Fail at a Remote Site 
The detection of AC-low from the remote site will immediately trigger 


the processing described in Section 18.5.1. The absence of AC-low 
will automatically return the unit to the "ready" status. 
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If specified, the state of the following remote modules will then be 
restored as described: 


1. Bistable outputs - set to last recorded state 
2. Counters - reinitialized to last initial value 


3. Analog outputs - restored to last output value 


18.5.3 Power Recovery at the Processor 


Power recovery by the processor will initiate the activity described 
in Section 18.5.2 for both local and remote file boxes. However, 
power recovery processing at the processor will not be reported to a 
task that is linked to error interrupts or connected to receive 
unsolicited interrupt data. 


18.5.4 Unit in Off-line Status 


A unit that is off line (see Section 18.3.9.1) is considered to be 
under manual control for purposes of diagnosis and maintenance. Under 
these conditions, error reporting as described in Section 18.5.1 is 
unnecessary and frequently undesirable, since fault indications are 
generally a by-product of these activities (that is, a remote unit is 
shut down to install an I/O module), not the result of a genuine 
controller fault. 


Furthermore, to permit the operation of diagnostic software, it is 
advisable to attempt to service all QIO requests regardless of the 
controller statuS. Consequently, under these circumstances, error 
reporting and detection are modified as follows when the controller is 
off Line: 


1. Access to the controller with the intention of transmitting 
data to or from the device is restricted to privileged tasks. 


2. The task linked to error interrupts and any tasks’ receiving 
interrupt data are not notified of remote power-fail or fatal 
serial line errors. 


3. All device error interrupts become disabled. 


4. An attempt is made to Service all QIO requests if issued by a 
privileged task. If such requests time out (that is, A/D 
converter or remote terminal output), they are terminated 
with the error code IE.ABO rather than with IE.DNR. No 
hardware errors are reported for I/0 requests that are 
normally completed immediately (for example, bistable digital 
output). 
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18.5.5 Error Data - ICSR and ICAR Registers 


Whenever. a reportable error occurs, the driver returns the contents of 
the appropriate control and status register (ICSR) and, in some cases, 
the contents of the address register (ICAR), to assist in fault 
diagnosis. Tables 18-8 and 18-9 describe the contents of these 
registers. 


Table 18-8 
ICSR Contents 


Bit Name Read/ Description 
Write 


| 15 ae BUSY Indicates output buffer cannot 
accept new data. 
14 |MAINT R/W Maintenance. 
hee al USED R Always set to l. 
12 |ERROR R Indicates occurrence of 
communication serial line error. 


Reset when ICAR is read. 


11 |MAINT R/W Maintenance. 
| 10 | PwR FAIL R Remote Power Supply AC LO indicator. 
| 
9 TBMT INT EN R/W Enables bit 15 of ICAR to interrupt. 
| 8 !IMAINT | R/W | Maintenance. 
7 MOD INT R Indicates I/O Module requires 
interrupt servicing. 
6 RESET W Resets all I/O modules. Always read 
as 0. 
5 TTY ENABLE R/W Activates TTY mode, disables I/0 
mode. 
4 PWR FAIL INT R/W Enables bit 10 to interrupt. 
ENABLE 
3 BMT INT ENABLE R/W Enables complement of bit 15 to 
interrupt. 
2 MOD INT ENABLE R/W Enables Bit 7 to interrupt. 
1 ERROR INT ENABLE R/W Enables Bit 12 to interrupt. 
0 pREe R/W Resets the interrupting module's 
| flag when set and the module is 


addressed. This clearing action 
also resets the RIF bit. 
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Table 18-9 
ICAR Contents 


15 TBMT Indicates TTY output buffer can 
accept new data. 


14 PCL Pulse closed. This bit is set by a 
jumper on a digital interrupt 
module. This jumper is removed if 
contact closures are not of interest 
to the user. 


3 POP Pulse Opened. This bit is set by a 
jumper on a digital interrupt 
module. This jumper is removed if 
contacts opening are not of interest 
to the user. 


12 DA Indicates terminal character has 
been received. Cleared by reading 
terminal character. 


11-08 Generic Code A 4-bit binary code that identifies 
the type of module requesting the 
interrupt. 


07-00 Module Address 8-bit address of the module 
requesting the interrupt. 


18.6 DIRECT ACCESS 


Section 18.1.3 notes those ICS/ICR11 functions that may be performed 
by referencing a module through its physical address in the I/0 
page. Under RSX-11M such access is accomplished by one of the 
following methods: 


1. <A privileged task or any task running in an unmapped system 
has unrestricted access to the I/O page and may therefore 
access each module by absolute address. 


2. Using the Task Builder, a task may link to a global common 
area whose physical address limits span a set of locations 
in the I/O page. This method applies to either a mapped or 
unmapped system. 


The latter method allows a task to be transported to any other 
system simply by relinking. Moreover, in a mapped system the memory 
management hardware aborts all references to device registers 
outside the physical address limits of the common block. 


Because the software allows arbitrary module placement, direct 
reference, in either case, must be accomplished by translating a 
relative module number to a physical or virtual register address 
within the I/O page. This translation or mapping is performed by 
means of a table (ICTAB.MAC) that iS created during system 
generation, and inserted in the system object module library. 
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The operations required to implement each method may be summarized 
as follows: 


1. 


Unrestricted access to the I/O page 


ae 


Based upon the user's response to the ICS/ICR SYSGEN 
queries, the MACRO - source file ICTAB.MAC is 
automatically created under UIC [11,10] on the source 
disk. This file contains tables that describe the 
physical location of each counter, digital interrupt, 
and digital sense module in the target system. 


ICTAB.MAC is assembled for eventual inclusion in the 
system object module library. 


The MACRO source file ICOM.MAC, under UIC [11,10] on 
the source disk, is assembled to generate global 
definitions for the first ICS/ICR address on the _ I/0 
page and the number of ICS/ICR controllers in the 
target system. The resulting object file is 
incorporated in the system library file. 


A task is built containing the appropriate global 
references. Such references are resolved when the Task 
Builder automatically searches the system library. 


Steps a, b, and c are executed once. Step d is performed 
each time a task that references the ICS/ICR11 is created. 


NOTE 


ICS/ICR inputs are not valid until 3ms after power 
recovery at the processor. Tasks that are 
referencing inputs directly may establish a power 
recovery AST entry point that suspends task 
execution for the necessary time interval. 


Access to the I/O page through a Global Common Block: 


ae 


b. 


Steps a and b are performed. 


File ICOM.MAC under UIC [11,10] is assembled to define 
the first ICS/ICR module address as a relocatable 
value, the number of I/O page locations required, and 
the number of controllers present on the target system. 


File ICOM.OBJ, created in step b, is linked using the 
Task Builder to create an image of the device common 
block on disk. 


The SET and INSTALL MCR or VMR commands are used _ to 
allocate space for the common block and declare the 
block resident in the target system. 


A task is created containing the appropriate global 
references to the common block and mapping table. 
Common block references are resolved by directing the 
Task Builder to link the task to the device common 
block (ICOM). The mapping table reference is’ resolved 
from the system library module ICTAB. 
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The detailed procedure for creating the necessary object files and 
device common block is performed automatically as part of the system 
generation process, and is described fully in the RSX-11M System 
Generation and Management Guide. Therefore, the discussion in the 
following paragraphs is limited to procedures for linking to’ the 
device common block, and uSing the file ICTAB.MAC to determine 
module addresses within the I/O page. 


18.6.1 Linking a Task to the ICS/ICR Common Block 


Once the device common block has been created, a task may access 
ICS/ICR modules by linking to the common block. This can be done by 
using the Task Builder commands shown in the following example: 


TKB>TASK, LP: =TASK. OBJ 
TKB>/ 

ENTER OPTIONS: 

TKB> COMMON=ICOM:RO- 
TKB>/ 


The illustration is valid for either a mapped or unmapped system. 
In both cases, the Task Builder links the task to the common block 
by relocating the global symbol definitions contained in the common 
block symbol table file ICOM.STB located under UIC [1,1]. If memory 
management is present, the Executive will map the appropriate 
physical locations into the task's virtual addressing space when the 
task is made active. 


18.6.2 Accessing the I/O Page 


After the task has been linked to the I/O page, either directly or 
through reference to the device common block, access to a specific 
ICS/ICR counter, or digital input modules during task execution, is 
a 3-step process: 


1. The task generates a request for module data by specifying 
module type, relative module number, and physical unit 
number. 


2. The data contained in module ICTAB is accessed to translate 
the arguments of step 1 to a physical offset from the 
ICS/ICR base address on the I/O page. 


3. The ICS/ICR base address, defined in the common block or 
system library module that was created from file ICOM.MAC, 
is added to the offset to compute a physical or virtual 
address and the module data is read. 


The next few paragraphs describe the format of the system library 


module ICTAB, and common block module ICOM in detail. A sample 
MACRO subroutine that references these modules is then presented. 
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18.6.2.1 Mapping Table Format - The mapping table created by SYSGEN 
(file ICTAB.MAC) is used to translate module type, relative module 
number, and physical unit number for counter, digital interrupt, and 
digital sense modules, to the physical or virtual address of the 
module on the I/O page. This module must be assembled and inserted 
in the system object module library before the standard FORTRAN 
callable routines can be used to read digital input and _ counter 
modules. The table contains one set of entries for each physical 
unit. The entry sets are arranged in order of ascending unit number 
(Figure 18-1). Entries within each unit are arranged in sequence by 
module type, as shown in this figure. 


DIGITAL SENSE 
DIGITAL INTERRUPT UNIT 0 


MAPPING TABLE 


COUNTER MODULES 


DIGITAL SENSE 
DIGITAL INTERRUPT 
COUNTER MODULES 


Figure 18-1 Mapping Table Format 


INCREASING 
MEMORY 
ADDRESSES 


UNIT N 
MAPPING TABLE 


ZK-009-81 


The structure of each entry is depicted in Figure 18-2. Entries are 
18 bytes long. Byte 0 contains the highest number of modules of a 
given type that can be referenced for the controller. Bytes 2 
through 17, when indexed by relative module numbers, yield a value 
between 0 and 255 representing the physical location of the module 
within the set of external page addresses allocated to the 
ICS/ICRI1. 


The following global symbols are defined by this module: 


2IGTAB Location of mapping tables 


I.€TBL Length in bytes of one set of entries 


18.6.2.2 I/0 Page Global Definitions - As previously mentioned, 
module ICOM contains symbolic definitions for I/O page references 
that are resolved either through unrestricted access or by means of 
a device common block that is resident on the I/O page. The 
procedures for implementing either method are carried out during 
system generation. Upon completion, the following global symbols 
are defined and later referenced by the FORTRAN callable 
subroutines: 


First ICS/ICR virtual or physical address within the 
I/O page. 


- ICMD 


I$SCll = Number of ICS/ICR controllers 
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If the global common block was built, the definitions above are 
contained in the symbol table file that was created by the Task 
Builder; otherwise, they are included in the system object module 
library.1t 


BYTE 
RESERVED MAX. MODULE NO. 0 
PHYSICAL MODULE NO. | PHYSICAL MODULE NO. 2 
4 
6 
INCREASING 
MEMORY 8 
ADDRESS 
10 
12 
14 
16 
ZK-010-81 


Figure 18-2 Mapping Table Entry Format 


18.6.2.3 Sample Subroutine - The following subroutine, residing in 
the system library, utilizes the modules previously described, to 
read ICS/ICR module data. 

READ ICS/ICR-11 DIRECT ACCESS INPUTS 

LOCAL DATA 


ADDRESS OF ICS/ICR-11 MAPPING TABLES 


me Me me Be MEH NO Me 


-ENABL LSB 


N=0 ; 
ICMAP: ; 
- REPT Les 
-WORD - ICTAB+I.CTBL*N> 
N=N+1 
« ENDR 
7+ 


1. The definitions are included in module ICOM in the system library 
or in the STB file ICOM.STB under UIC[1,1] on the system disk. The 
STB file is automatically referenced by the Task Builder in response 
to the use of the LIBR keyword. 
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**—.RDIC-READ ICS/ICR-11 DIRECT ACCESS INPUTS 


THIS SUBROUTINE IS CALLED TO TRANSLATE RELATIVE MODULE NUMBER 
TO PHYSICAL EXTERNAL PAGE ADDRESS AND READ THE MODULE DATA. 


RELATIVE MODULE NUMBER 
MODULE CODE 


WHERE: 


0 = CONTACT SENSE 
1 = CONTACT INTERRUPTS 
2 = COUNTERS 

STACK SETUP IS AS FOLLOWS: 


(SP)+00 = RETURN TO CALLER 
(SP)+02 = I/O STATUS BLOCK ADDRESS (NOT 
EFERENCED). 
(SP)+04 = PHYSICAL UNIT NUMBER 
OUTPUTS: 
C/CLEAR 
RO = MODULE DATA 
C/SET: 
NONEXISTENT PHYSICAL UNIT NUMBER OR MODULE 
PECIFIED 
~RDIC:: ; 
MOV 4(SP),R2 ; GET PHYSICAL UNIT NUMBER 
CMP #ISSC11-1,R2 ; LEGAL UNIT NUMBER? 
BLO 10$ ; IF LO NO 
ASL R2 3; CONVERT PHYSICAL UNIT NUMBER 
TO WORD 
; OFFSET 
MOV ICMAP(R2) ,R2 3; GET ADDRESS OF MAPPING TABLE 
; ENTRIES FOR THIS UNIT 
ASL Rl 3; CONVERT CODE TO WORD OFFSET 
ADD R1,R2 3; MULTIPLY OFFSET BY 9 AND ADD 
; TO TABLE ADDRESS 
ASL Rl owe 
ASL Rl og woe 
ASL Rl o. sgciee 
ADD R1,R2 s COMPUTE OFFSET TO TABLE 
TSTB (R2) ; MODULE EXIST? 
SEC ; ASSUME NO 
BEQ 10$ ; IF EQ NO 
INCB RO ; CONVERT TO NUMBER OF MODULES 
CMPB (R2)+,R0 ; LEGAL MODULE NUMBER? 
BLO 10$ 3; IF LO NO 
INC R2 ; POINT TO TABLE ENTRIES 
ADD RO,R2 3; OFFSET TO MODULE NUMBER 
CLR RO ; SET FOR MOVB WITHOUT SIGN 
EXTEND 
BISB (R2),R0 : GET INDEX TO MODULE 
ASL RO 3; CONVERT TO WORD OFFSET 
MOV - ICMD (RO) ,RO 3; GET MODULE DATA 
108: ; 
RETUR : 
«END 


1 
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18.7 CONVERSION OF EXISTING SOFTWARE 


The following paragraphs are intended as guidance in converting 
existing UDC or ICS software to run under the ICS/ICR-11 driver and 
associated FORTRAN support routines. The differences described here 
are restricted to module support and features that would affect 
existing software. New features, unsupported in previous systems, 
are not discussed. 


18.7.1 Features 
Principal features affecting existing software are: 


1. Support for the ICS/ICR11 as a multiunit, multicontroller 
device 


2. Removal of software restrictions on the placement of 
functionally similar modules 


Multiunit support affects any software that addresses modules 
outside the range of a single file box. In general, such software 
must be modified at the source level. 

Unrestricted module placement affects MACRO-11 programs that 
directly access digital input and counter modules. Such programs 


may utilize the library routine described in Section 18.3 to read 
data from these modules. 


18.7.2 Module Support 


18.7.2.1 IAD-IA A/D Converter and IMX-IA Multiplexer 
MACRO Interface: 


Identical to UDC11 driver 


FORTRAN Interface: 


Same as UDC11 


Functional Differences: 


The ICS/ICR driver can initiate parallel conversions on _ each 
IAD-IA in a file box that is referenced by a single QIO 
request. The UDCl1 driver performs all conversions serially. 


The ICS/ICR driver supports any permissible configuration of 
IAD-IA A/D converters and IMX-IA multiplexers. The UDC11 
driver requires that eight module slots be reserved for each 
IAD-IA in the system regardless of the actual number of 


multiplexers installed. 
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18.7.2.2 16-Bit Binary Counter 
MACRO Interface: 


Identical to UDC11 driver 


FORTRAN Interface: 
Same as UDC11; however, if the counter is read through a call 


to RDTI, then the task must be relinked to incorporate the 
revised FORTRAN Interface routine. 


The ICS/ICR driver permits any task to reset an initial counter 
value (with FORTRAN call SCTI or through the I0.ITI QIO 
function). The UDCl1 driver restricts this operation to a task 
that has connected to counter interrupts. 


18.7.2.3 Bistable Digital Output 
MACRO Interface: 


Identical to UDCll 


FORTRAN Interface: 


Identical to UDC1l1l 


Functional Differences: 


None 


18.7.2.4 Momentary Digital Output 

MACRO Interface: 
User interface is achieved with the QIO IO.MSO issued to the 
ICS/ICR-11 driver. The UDC1l1 driver does not support this 
function since the module may be accessed directly through the 
UDC device common block. 

FORTRAN Interface: 
Identical to UDCl1l; however, existing FORTRAN tasks must be 
relinked to include ICS/ICR11 FORTRAN interface routines. 


Functional Differences: 


Momentary output operations are now processed by the ICS/ICR 
driver, rather than through direct access to the I/O page 
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18.7.2.5 Noninterrupting Digital Input 
MACRO Interface: 
MACRO Interface is by means of the ICS/ICR11 device common 
block and mapping table described in Section 18.6. 
FORTRAN Interface: 
Identical to UDCl1; however, existing tasks must be relinked 
to include revised ICS/ICR11 FORTRAN interface routines. 
Functional Differences: 


None 


18.7.2.6 Analog Output 

MACRO Interface: 
User interface is achieved with the QIO IO.SAO issued to the 
ICS/ICR driver. The UDC11 driver does not support this 
function since the module may be accessed directly through the 
UDC device common block. 

FORTRAN Interface: 
Identical to UDC11; however, existing FORTRAN tasks must be 
relinked to include ICS/ICR11 FORTRAN interface subroutines. 


Functional Differences: 


Analog output operations are now processed by the ICS/ICR 
driver rather than through direct access to the I/O page. 


18.7.2.7 Interrupting Digital Input 
MACRO Interface: 


Identical to UDC11 driver 


FORTRAN Interface: 
Identical to UDCll driver; however, if digital inputs are read 


through the call to RCIPT, then the task must be relinked to 
incorporate the revised ICS/ICR11 FORTRAN interface routines. 


Functional Differences: 


None 


CHAPTER 19 


NULL DEVICE DRIVER 


RSX-11M provides a driver for a software construct called the "null 
device." The mnemonic for the null device is NL:, and its 
characteristics are as follows: 


e A read from NL: returns an end-of-file error (IE.EOF). 

e A write to NL: immediately returns success (IS.SUC). 
The null device functions as a "black hole" to which you can direct 
output, and from which it will never return. It is particularly 
useful when used in conjunction with an indirect command file and MCR 
ASN commands, aS in the example below. 
Figure 19-1 shows the contents of a Task Builder command file called 
TESTBLD.CMD. Symbolic device names are used for the output file, map 
file, and input file. These names may be reassigned at task-build 
time. In particular, in the example below, the map file is assigned 
to the null device and thus is thrown away. 

>ASN SY:=0U: 

>ASN NL:=MP: 

>ASN DK1:=IN: 


>TKB @TESTBLD 


OU: TEST,MP: TEST=IN: [200,220] TEST 
7 


ASG=TI:2 
kA 


Figure 19-1 Indirect TKB Command File TESTBLD.CMD. 
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GRAPHICS DISPLAY DRIVER 


20.1 INTRODUCTION 

RSX-11M provides support for two graphics display peripherals: the 
VT1l1 and the vVS60. Graphics display drivers are not supported in 
RSX-11M-PLUS systems. Each consists of a CRT display, light pen, and 
display processing unit (DPU). Either may be purchased separately or 
as part of a complete system. For example, the GT46 is a "starter 


system" consisting of a VT11l and a PDP-11T/34 with 32K words of memory 
and disk storage. 


20.1.1 VT11 Graphics Display Subsystem 

The VT1l1 is a low-cost, line-drawing graphics display subsystem. It 
steals cycles asynchronously from the CPU whose UNIBUS it shares. Its 
DPU instruction set supports the following features: 


e Relative and absolute vectors -- solid, long dash, short dash, 
or dotted 


e Point plotting 

e Character generation 

e Blinking display 

e Eight levels of intensity 


e Light-pen interaction 


20.1.2 VS60 Graphics Display Subsystem 
The VS60 supports all these features at a higher rate of performance 


than the VTll. In addition, the VS60 supports hardware subroutining, 
scaling, and windowing. A second CRT may be added to the VS60. 


20.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the GET LUN INFORMATION system 
directive (the first characteristics word) contains Os in ali bits for 
graphics display devices. Words 3, 4, and 5 are undefined. 
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20.3 QIO MACRO 


Table 20-1 lists the standard and device-specific functions of the QIO 
macro that are valid for graphics display devices. 


The standard QIO functions IO.ATT and IO.DET have little use in the 


graphics display driver, because the specific functions IO.CON and 
IO.DIS are available. 


Table 20-1 
Standard and Device-Specific QIO Functions for Graphics Displays 


Srormee fF tinctton 


STANDARD FUNCTIONS | 


OLOSC: TOLATT ¢%-«% Attach device 


OLOSC TO.DET;..0« Detach device 
OTOSC “LOCKEE pean Cancel I/O requests 


DEVICE-SPECIFIC FUNCTIONS 


IO.CON,...,<Sstadd,size 
{,lpef][,lpast]> device (start DPU) 


EO CONT feo Continue (restart DPU) 


EO CDIS + 64% Disconnect from graphics 


CONNECT to graphics 
| 
device (halt DPU) | 


TO<STP}w28 Stop (halt DPU) 


stadd 


The starting address of a display file (must be word aligned). 
The display file must be within the lowest 28K of physical memory 
for the VTll. 

size 


The size of the display buffer in bytes. 


lpef 
The optional number of an event flag to be set upon light-pen 
hit; in the range 1-64 (10). 

lpast 


The optional address of an asynchronous system trap (AST) entry 
point to be used upon light-pen hit. 
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20.4 STATUS RETURNS 
Table 20-2 lists error and status conditions that are returned by the 


graphics display driver in the first word of the I/O status block. 
The second I/O status word always contains 0. 


Table 20-2 
Graphics Display Status Returns 


pce fmm 


The operation specified in the QIO directive was 
completed successfully. 


IE.ABO Operation aborted 


The I/O operation was cancelled by I0.KIL while in 
progress or in the I/O queue. 
IE.CNR Connection rejected 


The graphics device specified in an IO.CON function was 
already connected to another task. 


Device not attached 


The graphics device specified in an IO.DET function was 
not attached to the issuing task. 


Illegal event flag 


An event flag number specified in an I0.CON function 
(lpef argument) was not in the range 1-64 (decimal). 


IE. TFC Illegal function code 


A function code was specified in an I/O request that is 
illegal for graphics display devices. 


IE.SPC Illegal address space 


The display buffer specified in an I0.CON' function 
(stadd argument) was not word aligned, or (for VTll 
only) was not completely within the lowest 28K of 
memory. 


20.5 PROGRAMMING HINTS 


The graphics display driver does not determine what appears on _ the 
screen of the VT11 or VS60. The key to what is drawn is the 
collection of DPU instructions in the display buffer. 
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Under normal circumstances, the display buffer is generated by calls 
to a set of FORTRAN graphics subroutines. These subroutines provide a 
more convenient access to the graphics features of the hardware’ than 
do the raw DPU instructions. The subroutines are described in the 
DECgraphic-11 FORTRAN Reference Manual, order number DEC-11-GFRMA-A-D. 


Aborting a VT1l task may cause an RSX-11M system to hang’ up 
indefinitely, requiring a bootstrap. The VT1l1 DPU has no Halt 
instruction, but the I/O driver must halt the DPU before it can return 
a success status in response to an I0O.KIL request. (I0.KIL is 
automatically generated when a task is aborted.) This hang situation 
cannot arise with a VS60. 


CHAPTER 21 


LABORATORY PERIPHERAL ACCELERATOR DRIVER 


21.1 INTRODUCTION 


The Laboratory Peripheral Accelerator (LPA1l1-K) is an intelligent, 
direct memory access (DMA) controller for DIGITAL's laboratory data 
acquisition I/O devices. It is a fast, flexible, and easy-to-use 
microprocessor subsystem that allows analog data acquisition rates up 
to 150,000 samples per _ second. The LPA11-K is designed for 
applications requiring concurrent data acquisition and data reduction 
at high rates. 


The LPA11-K iS supported through a device driver and a set of 


program-callable routines. The device driver supports multiple 
controllers and can be configured as_ resident or loadable. The 
program-callable support routines are linked with the user's task at 
task-build time. These routines are highly modular. Therefore, a 


particular task contains only that code necessary for the facilities 
actually used. 


The LPAl1-K operates in two distinct modes: dedicated and 
multirequest. The subsections that follow Summarize each mode. 


21.1.1 LPA11-K Dedicated Mode of Operation 


In dedicated mode, only one user (that is, one request) can be active 
at a time and only analog I/O data transfers are Supported. Up to two 
analog converters can be controlled simultaneously. Sampling is 
initiated by an overflow of the real-time clock or by an externally 
supplied signal. 


21.1.2 LPA11-K Multirequest Mode of Operation 


In multirequest mode, sampling from all device types is supported. Up 
to eight users can be simultaneously active. The sampling rate for 
each user is a multiple of the common real-time clock rate. 
Independent rates can be maintained for each user. Both the sampling 
rate and the device type are specified as part of each data transfer 
request. 
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21.2 GET LUN INFORMATION MACRO 


If a Get LUN Information system directive is issued for a_ LUN 
associated with an LPAI11-K, word 2 (the first characteristics word) 
contains all zeros, words 3 and 4 are undefined, and word 5 contains a 
16-bit buffer preset value that controls the rate of the real-time 
clock interrupts. 


21.3 THE PROGRAM INTERFACE 


A collection of program-callable subroutines provides access to the 
LPA11-K. The formats of these calls are fully documented here for 
FORTRAN programs. MACRO-11 programmers access these same subroutines 
either through the standard subroutine linkage or through the use of 
two special-purpose macros. Optionally, MACRO-11 users can control an 
LPAl1-K directly through the use of device-specific QIO functions. 
Both FORTRAN and MACRO programs must contain at least one I/0 Status 
Block (IOSB) for retrieval of status information. The following 
subsections, therefore, describe: 


e The FORTRAN interface 
e The MACRO-11 interface 


e The I/O status block 


NOTE 
The subroutines documented in this 
chapter represent the high-level 


interface to the LPA11-K. Using these 
subroutines requires an understanding of 
hardware capabilities, configuration 
details, and hardware status codes as 
described in the LPA11-K Laboratory 
Peripheral Accelerator User's Guide. 


21.3.1 FORTRAN Interface 


Table 21-1 lists the FORTRAN interface subroutines for accessing the 
LPA11—-K. 


The calling sequences of the routines listed in Table 21-1 are 
compatible with the K-series support routines, described in Chapter 
22, except as noted. The following subsections briefly describe the 
function and format of each FORTRAN subroutine call. 
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Table 21-1 
FORTRAN Subroutines for the LPA11-K 


jsubrootine | metion 


ADSWP 


Initiate synchronous A/D sweep 


CLOCKA 


Set Clock A rate 


| | 
CLOCKB Control Clock B | 
CVADF Convert A/D input to floating point 
| DASWP | Initiate synchronous D/A sweep | 
| DISWP | Initiate synchronous digital input sweep 
DOSWP Initiate synchronous digital output Sweep 
FLT16 Convert unsigned integer to a real constant 
IBFSTS Get buffer status | 
IGTBUF Return buffer number 
INXTBF Set next buffer 
IWTBUF Wait for buffer | 
LAMSKS Set masks buffer 
RLSBUF Release data buffer 


RMVBUF Remove buffer from device queue 


SETADC Set channel information 


SETIBF Set array for buffered sweep 


STPSWP Stop sweep 


XRATE Compute clock rate and preset 


21.3.1.1 ADSWP: Initiate Synchronous A/D Sweep - The ADSWP routine 
initiates a synchronous A/D input sweep through an LPS-11l or an AD11-K 
(and, if present, the AM11-K). 


If differential input is desired for the AD11-K/AM11-K, the channel 


increment must be set to 2 by calling the SETADC routine. The default 
channel increment is 1 (single-ended input). 
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The ADSWP call is as follows: 


ibuf 


lbuf 


nbu 


mode 


CALL ADSWP (ibuf,lbuf,!nbuf],[mode],[({idwell],[iefn],[{ldelay], 
fichn],[nchn], [ind] ) 


A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (IOSB). 


The size in words of each data buffer. All data buffers must be 
equal in size and Ilbuf must be greater than 5. In dedicated 
mode, lbuf must be at least 257 words. 


The number of buffers to be filled. If nbuf is omitted or set 
equal to 0, indefinite sampling occurs. The STPSWP routine 
terminates indefinite sampling. 


The sampling options. The default is 0. The mode bit values 
listed below that are preceded by a plus sign (+) are independent 
and can be added or ORed together (assuming that the sampling 
options are applicable to the mode of operation). Those values 
not preceded by a plus sign are mutually exclusive and only one 
such value can be used at atime. All bit values not listed 
below are reserved. 


The following values can be specified: 


0 Absolute channel addressing (default). This mode 
allows the user to directly access all 64 channels of 
an A/D converter. 


+32 Dual A/D conversion serial/parallel. This option 
applies to dedicated mode only. It is ignored in 
multirequest mode. 


+64 Multirequest mode. If this value is not specified, the 
request is for dedicated mode. If the request mode 
does not match the mode of the hardware (that is, 
different microcode in the master microprocessor), the 
LPA11-K rejects the request with an appropriate error 
code. 


+512 External trigger (STl). This mode is used when a 
user-Supplied external sweep trigger is desired. The 
external trigger is supplied by a jumper connecting the 
AD11-K External Start input to the kKW11-K Schmitt 
Trigger 1 output. This external trigger connection can 
only be used in Dedicated Mode. If mode 512 is 
selected, the user task must specify a Clock A rate of 
-1 for proper A/D sampling. This is non-clock-driven 
sampling. 
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+1024 Time stamp with Clock B (Multirequest mode only). 


+2048 Event marking (Multirequest mode only). LAMSKS must be 
called to specify an event mark channel and event mark 
mask. 


+4096 Start method. If set, digital input start. If clear, 
immediate start. LAMSKS muSt be called to specify a 
digital start channel and digital start mask 
(multirequest mode only). 


+8192 Dual A/D converter (dedicated mode only). 


+16384 Data overrun NON-FATAL/FATAL. Tf selected, data 
overrun is considered nonfatal. The LPA11-K 
automatically defaults to fill buffer 0. (See Section 
21.4 for a discussion of buffer management.) 


idwell 
The number of clock overflows (pulses) between data sample 
sequences. AS an example, if idwell is 20 and nchn is 3, the 


iefn 


following occurs: after 20 pulses, one channel is sampled on 
each of the next three pulses. Then, no sampling takes place for 
the next 20 pulses. In multirequest mode, this facility permits 
different sample rates for the same hardware clock rate and 
preset. In dedicated mode, the clock hardware rate controls 
sampling and this idwell argument is ignored. 


If compatibility with K-series support routines is desired, the 
user task must first establish the clock preset by calling the 
CLOCKA routine. The default idwell value of 1 is used in the 
Sweep start command. For the K-series, this procedure sets the 
rate as desired. 


NOTE 


This parameter is called iprset in the K-series support 
routines described in Chapter 22. Its function is 
different from the idwell parameter described here. 


The event flag (1 to 28, 30 to 96), the name of a completion 
routine, or 0. If O or defaulted, event flag 30 will be used for 
internal synchronization. If iefn is an event flag, the selected 
event flag is set as each buffer is filled. Note that event flag 
29 is reserved for use by the LPAl1-K support routines’ for 
internal synchronization. If iefn is greater than 96, it is 
considered to be a completion routine that will be called with a 
JSR PC. Such routines must return with an RTS PC (or a FORTRAN 
RETURN statement). 
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FORTRAN completion routines must not contain any of the 
following: 


e Any 1/0 through the FORTRAN run-time system 
e Any use of virtual arrays 
e Any use of floating-point operations 


e Any errors, since error reporting is done through the FORTRAN 
run-time system 


e Anything else that may change the FORTRAN impure area 


Any of the above may result in fatal task errors or unpredictable 
results. 


If multiple sweeps are initiated, the user should. specify 
different event flags. Adherence to this limitation cannot be 
enforced by the software. 


ldelay 


ichn 


nchn 


ind 


The delay from the start event (DR11-K) until the first sample in 
IRATE units. This feature is supported in multirequest mode 
only. Default or 0 indicates no delay. 


The number of the first channel to be sampled. The default of 0 
applies only if ichn was not established in a prior call to the 
SETADC routine. 


The number of channels to sample. The default is 1. nchn may be 
set up with the SETADC routine. The number of channels specified 
are sampled at a rate of 1 per clock interrupt. If nchn equals 
the single channel bit is set in the mode word of the start 


Receives a success or failure code as follows: 
1 indicates that the sweep was successfully initialized. 


0 indicates an illegal argument list, or SETIBF was not 
called prior to this call. 


-l indicates a QIO directive failure. The directive error 
code is placed in IOSB(1) in IBUF. 


NOTE 
The ind parameter is not supported by the kK-series 
support routines. If compatibility with K-series 
support routines is desired, this parameter must be 
ignored. 
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21.3.1.2 CLOCKA: Set Clock A Rate - The CLOCKA routine sets the rate 
for Clock A. This routine is called as follows: 


CALL CLOCKA (irate,iprset,[ind],[lun]) 


irate 


The clock rate. One of the following must be specified: 


-l Direct-coupled Schmitt Trigger 1 (used only for A/D sweeps 
in Dedicated Mode +512; not supported by K-series support 
routines) 

Clock B overflow or no rate 

1 MHz 

100 KHz 

10 KHz 

1 KHz 

100 Hz 

Schmitt Trigger 1 

Line frequency 


SNOB WMH © 


iprset 


ind 


lun 


21,3 


The two's complement value for clock preset. The clock rate 
divided by the negative clock preset value yields the clock 
overflow rate. For example, to obtain a clock overflow rate of 
10 Khz with a clock rate of 1Mhz, iprset = -100 (minus 100 
decimal). The XRATE routine can be used to calculate a clock 
preset value. 


Receives a success or failure code as follows: 
0 indicates an illegal argument list or I/O error. Possible 
causes are: microcode not loaded; driver not loaded; 
device off line or not in system. 


1 indicates Clock A set to start when sweep requested. 


The logical unit number. The default is 7. 


-1.3 CLOCKB: Control Clock B - The CLOCKB routine gives the user 


control over the KW11-K Clock B. 


The CLOCKB call is as follows: 


CALL CLOCKB ([irate],iprset,mode,lind],[lun] ) 
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irate 


iprse 


mode 


ind 


lun 
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The clock rate. When irate is nonzero, the clock is set running 
at the selected rate after the preset value specified by iprset 
is loaded. A 0 irate stops the clock. When irate is 0 or 
default, the iprset and mode parameters are ignored. 


The following values are acceptable for irate: 


Stop clock B 

1MHz 

100 KHz 

10 KHz 

1 KHz 

100 Hz 

Schmitt Trigger 3 
Line frequency 


SNOOP WNHH CO 


t 


The count by which to divide clock rate to yield overflow rate. 
Overflow events can be used to drive clock A. The preset 
parameter must be specified as 0 or as a negative number in the 
range -l to -255. The value in iprset can be established by use 
of the XRATE routine. 


The options. The mode bit values listed below that are preceded 
by a plus sign (+) are independent and can be added or ORed 
together. Those values not preceded by a plus sign are mutually 
excluSive and only one such value can be used at a time. All bit 
values not listed below are reserved. 


1 indicates Clock B operates in noninterrupt mode. The 
16-bit clock is not incremented or altered. This allows a 
greater than l10KHz pulse to be sent to Clock A. 


+2 indicates the feed B to A bit will be set in tthe Clock B 
status register. 


Receives a success or failure code as follows: 
0 indicates an illegal argument list or I/O error. Possible 
causeS are: Microcode not loaded; driver not loaded; 
device off line or not in system. 


1 indicates Clock B started. 


The logical unit number (LUN). The default LUN is 7. 
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21.3.1.4 CVADF: Convert A/D Input to Floating Point - The CVADF 
routine converts an A/D input value to a floating-point number. The 
routine can be invoked as a subroutine or a function as follows: 


CALL CVADF (ival,val) 


or 
val = CVADF(ival) 

ival 
A value obtained from A/D input. Bits 12-15 are 0. Bits 0O-ll 
represent the value. 

val 


(REAL*4) receives the converted value. The converted value is 
calculated with the following formula: 


val = (64*ival)/gain 


21.3.1.5 DASWP: Initiate Synchronous D/A Sweep - The DASWP routine 
initiates synchronous D/A output to an AAI11-K. 


The DASWP call is as follows: 

CALL DASWP (ibuf,lbuf,[nbuf],[{mode],fidwell],{iefn],ldelay, 
fichn],fncehn],find]) 

ibuf 
A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (IOSB). 

lbuf 
The size in words of each data buffer. All data buffers must be 
equal in size and tlbuf must be greater than 5. In dedicated 
mode, lbuf must be at least 257 words. 

nbuf 
The number of buffers to be emptied. If nbuf is omitted or set 
equal to 0, indefinite sweeping occurs. The STPSWP routine 
terminates indefinite sweeping. 

mode 
The start criteria. Except where noted, the plus’ sign (+) 
preceding mode bit values listed below indicates that they are 


independent and can be added or ORed together. All bit values 
not listed below are reserved. 
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The following values can be specified: 
0 indicates immediate start. This is the default. 


+64 Multirequest mode. If this value is not specified, the 
request is for dedicated mode. If the request mode 
does not match the mode of the hardware (that is, 
different microcode in master microprocessor), the 
LPA11-K rejects the request with an appropriate error 
code. 


+4096 Start method. If set, digital input start. If clear, 
immediate start. LAMSKS must be called to specify a 
digital start channel and ae digital start mask 
(multirequest mode only). 


+16384 Data overrun NON-FATAL/FATAL. Tf selected, data 
overrun is considered nonfatal. The LPA11-K 
automatically empties buffer 0. (See Section 21.4 for 
a discussion of buffer management.) 


idwell 


iefn 


The number of clock overflows (pulses) between data sample 
sequences. For example, if idwell is 20 and nchn is 3, the 
following occurs: After 20 pulses, one channel is emptied on 
each of the next three pulses. Then, no emptying takes place for 
the next 20 pulses. In multirequest mode, this facility permits 
different rates for the same hardware clock rate and preset. In 
dedicated mode, the clock hardware rate controls sampling and 
idwell in the sweep start command is ignored. 


If compatibility with K-series support routines is desired, the 
user task must first establish the clock preset by calling the 
CLOCKA routine. The default value (1) for the idwell parameter 
in the sweep start command must be used. For the K-series, this 
procedure sets the rate as desired. For the LPAI11-K, this 
Procedure results in idwell in the sweep call defaulting to l, 
thus yielding the same clock rate. 


NOTE 


This parameter is called iprset in the K-series support 
routines described in Chapter 22. Its function is 
different from the idwell parameter described here. 


is) 


An event flag number (1 to 28, 30 to 96), or the name of a 
completion routine, or 0. If O or default, event flag 30 is used 
for internal synchronization. If iefn is an event flag, the 
selected event flag is set as each buffer is filled. Note that 
event flag 29 is reserved for use by the LPA11-K support routines 
for internal synchronization. If iefn is greater than 96, it is 
considered to be a completion routine that will be called with a 
JSR PC. Such routines must return with an RTS PC instruction {or 
a FORTRAN RETURN statement). 
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FORTRAN completion routines must not contain any of the 
following: 
e@ Any I/O through the FORTRAN run-time system 
e Any use of virtual arrays 
e Any use of floating-point operations 


e Any errors, Since error reporting is done through the FORTRAN 
run-time system 


e Anything else that may change the FORTRAN impure area 


Any of the above may result in fatal task errors or 
results. 


If multiple sweeps are initiated, the user task should specify 
different event flags. This limitation cannot be enforced by the 
LPA11 driver. 


ldelay 


ichn 


nchn 


ind 


The delay from start event (DR11-K) until the first sample in 
irate units. A minimum delay of 150 microseconds is required 
(not verified by the LPA11 driver). This feature is supported in 
multirequest mode only. 


The first channel number. Default is channel number 0. 


The number of channels. Default is one channel. 


Receives a success or failure code as follows: 
1 indicates that the sweep was successfully initialized. 


0 indicates an illegal argument list, or SETIBF was not 
called prior to this call. 


-l indicates a QIO directive failure. The directive error 
code is placed in IOSB(1) in IBUF. 


NOTE 
The ind parameter is not supported by the K-series 
Support routines. If compatibility with K-series 
routines is desired, this parameter must be 
ignored. 
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21.3.1.6 DISWP: Initiate Synchronous Digital Input Sweep - The DISWP 
routine initiates a synchronous digital input sweep through a DR11-K. 
It can be called in multirequest mode only. 


The DISWP call is as follows: 


CALL DISWP (ibuf,lbuf,[{nbuf],[mode],[idwell],[iefn],[ldelay], 
{iunit],{nchn],[{ind]) 


ibuf 
A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (IOSB). 

lbuf 
The size in words of each data buffer. All data buffers must be 
equal in size and lbuf must be greater than 5. 

nbuf 
The number of buffers to be filled. If nbuf is 0 or defaulted, 
indefinite sampling occurs. The STPSWP routine is used to 
terminate indefinite sampling. 

mode 


The sampling options. The default is 0. The plus signs (+) 
preceding the mode bit values listed below indicate that they are 
independent and can be added or ORed together. All bit values 
not listed below are reserved. 


The following values can be specified: 
0 Immediate start. This is the default mode. 


+512 External trigger. The input sampling will be triggered 
by interrupts generated by the DRI11-K's’ external 
control lines, or its input bits if they are interrupt 
enabled. 


+1024 Time stamped sampling with Clock B. The double word 
consists of one data word followed by the value of the 
16-bit clock at the time of the sample. IOSB (2) 
contains the number of 2-word samples in the buffer. 


+2048 Event marking. LAMSKS must be called to specify an 
event mark word and an event mark mask. 


+4096 Start method. If specified, digital input start. Tf 


clear, immediate start. LAMSKS must be called to 
specify a digital start channel and a digital start 
mask. The digital start channel need not differ from 


the input channel (iunit). 


+16384 Data overrun NON-FATAL/FATAL. Le selected, data 
overrun is considered nonfatal. The LPALI-K 
automatically fills buffer 0. (See Section 21.4 for a 
discussion of buffer management.) 
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idwell 
The number of clock overflows (pulses) between data sample 
sequences. As an example, if idwell is 20 and nchn is 3, the 


following occurs: After 20 pulses, one channel is sampled on 
each of the next three pulses. Then, no sampling takes place for 
the next 20 pulses. In multirequest mode, this facility permits 
different sample rates for the same hardware clock rate and 
preset. 


If compatibility with K-series Support routines is desired, the 
user taSk must first establish the clock preset by calling the 
CLOCKA routine. The default value (1) for the idwell parameter 
in the sweep start command must be used. For the K-series, this 
procedure sets the rate as desired. For the LPA11-K, this 
procedure results in idwell in the sweep call defaulting to l, 
thus yielding the same clock rate. 


NOTE 
This parameter is called iprset in the kK-Series support 


routines described in Chapter 22. Its function is 
different from the idwell parameter described here. 


iefn 
An event flag number (1 to 28, 30 to 96), or the name of a 
completion routine, or 0. If default or a value of 0 is 
specified for iefn, event flag 30 is’ used for internal 
synchronization. If iefn is a valid event flag, the selected 
event flag is set as each buffer is filled. Note that event flag 
29 is reserved for use by the LPA11-K support routines for 
internal synchronization. If iefn is greater than 96, it is 
considered to be a completion routine that will be called with a 
JSR PC. Such routines must return with an RTS PC instruction (or 
a FORTRAN RETURN statement). 
FORTRAN completion routines must not contain any of the 
following: 
e Any I/0 through the FORTRAN run-time system 
e Any use of virtual arrays 
e Any use of floating-point operations 
e Any errors, since error reporting is done through the FORTRAN 

run-time system 

e Anything else that may change the FORTRAN impure area 
Any of the above may result in fatal task errors or unpredictable 
results. 
If multiple sweeps are initiated, the user task should specify 
different event flags. This limitation cannot be enforced by the 
LPA11 driver. 

ldelay 


The delay from start event (DR11-K) until the first sample in 
irate units. Default or 0 indicates no delay. 
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iunit 
The DR11-K unit number. Default is unit number 0. Values 0-4 
are valid. 
nchn 
The number of channels. The LPA1L1-K treats each DR11-K in its 
configuration as one channel. Default is 1 channel. 
ind 
Receives a success or failure code as follows: 
1 indicates that the sweep was successfully initialized. 


0 indicates an illegal argument list, or SETIBF was not 
called prior to this call. 


-l1 indicates a QIO directive failure. The directive error 
code is placed in IOSB(1) in IBUF. 


NOTE 


The nchn and ind parameters are not supported by 
the K-Series support routines. If compatibility 
with K-series support routines is desired, these 
last two parameters must be ignored. 


21.3.1.7 DOSWP: Initiate Synchronous Digital Output Sweep - The DOSWP 
routine initiates a synchronous digital output sweep through a DRII1-K. 
It can be called in multirequest mode only. 


The DOSWP call is as follows: 


CALL DOSWP (ibuf,lbuf,[([nbuf],[mode],{idwell],[{iefn],ldelay, 
{iunit],[{nchn],[ind]) 


ibuf 
A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (IOSB). 

lbuf 
The size in words of each data buffer. All data buffers must be 
equal in size and lbuf must be greater than 5. 

nbuf 


The number of buffers to be emptied. If nbuf is 06 or defauit, 
indefinite emptying occurs. The STPSWP routine is used to 


a 
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mode 
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The start criteria. 


The following values can be specified in the high-order byte of 
mode: 


0 Immediate start. This is the default mode. 


+512 External trigger. The output sampling will be 
triggered by interrupts generated by the DR11-K's 
external control lines or its input bits if they are 
interrupt enabled. 


+4096 Start method. If set, digital input start. If clear, 
immediate start. LAMSKS must be called to specify a 
digital start channel and a digital start mask. The 
digital start channel need not differ from the output 
channel (iunit). 


+16384 Data overrun NON-FATAL/FATAL. EE selected, data 
overrun is considered nonfatal. The LPA11-K 
automatically fills buffer 0. (See Section 21.4 for a 
discussion of buffer management.) 


idwell 


iefn 


The number of clock overflows (pulses) between data sample 
sequences. For example, if idwell is 20 and nchn is 3, the 
following occurs: After 20 pulses, one channel is activated on 
each of the next three pulses. Then, no output takes place for 
the next 20 pulses. In multirequest mode, this facility permits 
different output rates for the same hardware clock rate and 
preset. 


If compatibility with K-series support routines is desired, the 
user task must first establish the clock preset by calling the 
CLOCKA routine. The default value (1) for the idwell parameter 
in the sweep start command must be used. For the K-series, this 
procedure sets the rate as desired. For the LPA11-K, this 
procedure results in idwell in the sweep call defaulting to l, 
thus yielding the same clock rate. 


NOTE 


This parameter is called iprset in the K-series support 
routines described in Chapter 22. Its function is 
different from the idwell parameter described here. 


An event flag number (1 to 28, 30 to 96), or the name of a 
completion routine, or 0. If default or a value of 0 is 
specified for iefn, event flag 30 is_ used for internal 
synchronization. If iefn is a valid event flag, the selected 
event flag is set as each buffer is emptied. Note that event 
flag 29 is reserved for use by the LPA11-K support routines for 
internal synchronization. If iefn is greater than 96, it is 
considered to be a completion routine that will be called with a 
JSR PC. Such routines must return with an RTS PC instruction (or 
a FORTRAN RETURN statement). 
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FORTRAN completion routines must not contain any OF the 
following: 
e Any I/O through the FORTRAN run-time system 
e Any use of virtual arrays 
e Any use of floating-point operations 


e Any errors, Since error reporting is done through the FORTRAN 
run-time system 


e Anything else that may change the FORTRAN impure area 


Any of the above may result in fatal task errors or unpredictable 
results. 


If multiple sweeps are initiated, the user task should. specify 
different event flags. This limitation cannot be enforced by the 
LPA11 driver. 

ldelay 
The delay from start event (DR11-K) until the first sample in 
irate units. A minimum delay of 150 microseconds is required 
(not verified by the LPAI11 driver). 

iunit 
The DR11-K unit number. Default is unit number 0. Values 0-4 
are valid. 

nchn 
The number of channels. The LPA11-K treats each DR11-K in its 
configuration as one channel. Default is one channel. 

ind 
Receives a success or failure code as follows: 


1 indicates that the sweep was successfully initiated. 


0 indicates an illegal argument list, or SETIBF was not 
called prior to this call. 


-l1 indicates a QIO directive failure. The directive error 
code is placed in IOSB(1) in IBUF. 


NOTE 


The nchn and ind parameters are not supported by 
the K-series support routines. If compatibility 
with K-series support routines is desired, these 
last two parameters must be ignored. 
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21.3.1.8 FLT16: Convert Unsigned Integer to a Real Constant - The 
FLT16 routine converts an unsigned 16-bit integer to a real constant 
(REAL*4). It can be invoked as a subroutine or a function as follows: 


CALL FLT16 (ival,val) 


or 
val=FLT16(ivall,val]) 
ival 
An unsigned 16-bit integer. 
val 


The converted (REAL*4) value. 


21.3.1.9 IBFSTS: Get Buffer Status - The IBFSTS routine returns 
information on buffers being used in a sweep. 


The IBFSTS call is as follows: 


CALL IBFSTS (ibuf,istat) 


ibuf 


The 40-word array specified in the call that initiated a sweep. 


istat 


An array with as many elements as there are buffers involved in 
the sweep. The maximum is 8. IBFSTS fills each element in the 
array with the status of the corresponding buffer. The possible 
status codes are as follows: 


+2 indicates that the buffer is in the device queue. That 
is, RLSBUF has been called for this buffer. 


+] indicates that the buffer is in the user task queue. 
That is, it is full of data (for input sweeps) or is 
available to be filled (for output Sweeps). 


0 indicates that the status of the buffer is unknown. 
That is, it is not the current buffer nor is it in 
either the device or the user queue. 


-1l indicates that the buffer is currently in use. 


21.3.1.10 IGTBUF: Return Buffer Number - The IGTBUF routine returns 
the number of the next buffer to use. This routine should be called 
by user-task completion routines to determine which is the next buffer 
to access. It should not be used if an event flag was specified in 
the sweep-initiating call; if an event flag was specified, use the 
IWTBUF routine. 
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IGTBUF can be invoked aS a Subroutine or a function as follows: 
CALL IGTBUF (ibuf ,ibufno) 
or 


ibufno=IGTBUF (ibuf[,ibufno] ) 


ibuf 


The 40-word array specified in the call that initiated a sweep. 


ibufno 


Receives the number of the next buffer to access. If there is no 
buffer in the queue, ibufno contains -l. 


On the return from a call to IGTBUF, the following are the possible 
combinations of ibufno and IOSB contents: 


ibufno TOSB(1) IOSB(2) Explanation 
n 400 (8) (Word count) Normal buffer complete. 
n 1 (Word count) Buffer complete. Sweep 
terminated. There may be 


additional buffers in the 
queue filled and ready for 
processing. 


-l 0 0 No buffers in queue. 
Request still active. 


=): a 0 No buffers in queue. Sweep 
terminated. 


-l RSX-11M LPA11-K No buffers in queue. 
error code(10) error code(8) Sweep terminated due to 
error condition. (Refer to 
Section 21.3.3 for error 
code summary.) Note that 
the error is not’ returned 
until there are no more 

buffers in the user queue. 


21.3.1.11 INXTBF: Set Next Buffer - The INXTBF routine alters’ the 
normal buffer selection algorithm. It allows the user task to specify 
the number of the next buffer to be filled or emptied. 

INXTBF can be invoked as a Subroutine or a function as follows: 


CALL INXTBF (ibuf,ibufno[,ind] ) 


or 
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ibuf 
The 40-word array specified in the call that initiated a sweep. 
ibufno 
The number of the next buffer the user wants filled or emptied. 
The buffer must already be in the device queue. 
ind 


Receives an indication of the result of the operation: 


0 indicates that the specified buffer was not in the device 
queue. 


1 indicates that the next buffer was successfully set. 


21.3.1.12 IWTBUF: Wait for Buffer - The IWTBUF routine allows a_ user 
task to wait for the next buffer to fill or empty. It should be used 
in conjunction with the specification of an event flag in the 
sweep-initiating call. This routine should not be used if a 
completion routine was specified in the call to initiate a sweep; 
when event flags are specified, use the IGTBUF routine. 


IWTBUF can be invoked as a subroutine or a function as follows: 


CALL IWTBUF (ibuf,[iefn],ibufno) 


or 
ibufno=IWTBUF (ibuf,fiefn],[ibufno]) 

ibuf 
The 40-word array specified in the call that initiated a sweep. 

iefn 
The event flag on which the task will wait. This should be the 
same event flag as that specified in the sweep-initiating call. 
If iefn equals 0 or default, event flag 30 is used. 

ibufno 


Receives the number of the next buffer to be filled or emptied by 
the user task. 
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On the return from a call to IWTBUF, the following are the possible 
combinations of ibufno and IOSB contents: 


ibufno IOSB(1) IOSB (2) Explanation 
n 400 (8) (word count) Normal buffer complete. 
n 1 (word count) Buffer complete. Sweep 
terminated. There may be 


additional buffers in the 
queue filled and ready for 
processing. 


=1 1 0 No buffers in queue. 
Sweep terminated. 


-l RSX-11M LPA11-K No buffers in queue. 
error code(10) error code(8) Sweep terminated due _ to 
error condition. (Refer 


to Section 2s Seno for 
error code summary.) Note 
that the error is not 
returned until there are 
no more buffers in the 
user queue. 


21.3.1.13 LAMSKS: Set Masks Buffer - The LAMSKS routine initializes a 
user buffer containing a LUN, a digital start mask and event mark 
mask, and channel numbers for the two masks. The routine then assigns 
the LUN. Each DR11-K is considered to be one channel. Each channel 
has both input and output capabilities. 


LAMSKS must be called if digital input starting or event marking is to 
be utilized, or if a LUN other than the default LUN 7 will be assigned 
to LAO. LAMSKS must also be called if multiple LPA11-Ks are being 
used. If LAMSKS is to be called, it must be called prior to calling 
SETIBF. Unlike SETIBF, LAMSKS does not have to be called before each 
sweep initiation unless one or more parameters are to be changed. 

The LAMSKS call is as follows: 

CALL LAMSKS (lamskb,{lun],[iunit],[idsc],[fiemc],[idsw], 
[iemw],[ind]) 


lamskb 


A 4-word array. 


lun 


A logical unit number. Default LUN is 7. 
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iunit 
The physical unit number of the LPA11-K. Default physical unit 
number is LAQ. 

idsc 


The digital start word channel. Default is channel 0. 


iemc 


The event mark word channel. Default is channel 0. 


idsw 
The digital start word mask. Default is 0 (disable digital input 
starting). 

iemw 


The event mark word mask. Default is 0 (disable event marking). 


ind 
Receives a success or failure code as follows: 
1 indicates successful initialization. 
OQ indicates an illegal argument list. 
-n indicates a LUN assignment failure. n is the directive 
error code. 
NOTE 
If compatibility with K-series support routines is 


desired, ignore this parameter. 


For a discussion of event marking and digital starting, see the 
LPA11-K Laboratory Peripheral Accelerator User's Guide. 


21.3.1.14 RLSBUF: Release Data Buffer - The RLSBUF routine declares 
one or more buffers free for use by the interrupt service routine. 


The RLSBUF routine must be called to release buffer(s) to the device 
queue before the sweep is initiated. The device queue must always 
contain at least one buffer to maintain continuous sampling. 
Otherwise, buffer overrun occurs (See Section 21.4 for a discussion of 
buffer management). Note that RLSBUF does not verify whether the 
specified buffers are already in a queue. 
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The RLSBUF call is as follows: 


CALL RLSBUF (ibuf,[{ind],n0[,nl...,n7]) 


ibuf 


The 40-word array specified in the call that initiated a sweep. 


ind 
Receives a success or failure code as follows: 
0 indicates illegal buffer number specified, illegal number 
of buffers specified, or a double buffer overrun has been 
detected. 


1 indicates buffer(s) successfully released. 


n0O,nl,etc. 


The numbers (0-7) of the buffers to be released. A maximum of 
eight can be specified. 


21.3.1.15 RMVBUF: Remove Buffer from Device Queue = The RMVBUF- rou- 
tine removes a buffer from the device queue. 


The RMVBUF call is as follows: 


CALL RMVBUF (ibuf,n[,ind]) 


ibuf 


The 40-word array specified in the call that initiated a sweep. 


n 
The number of the buffer to remove. 
ind 
Receives a success or failure code as follows: 
0 indicates that the specified buffer was not in the device 
queue. 
1 indicates that the specified buffer was removed from the 
queue. 
21.3.1.16 SETADC: Set Channel Information - The SETADC routine 
establishes channel start and increment information for all sweeps. 
The SETIBF routine must be called to initialize the 40-word array 


(ibuf) before SETADC is called. 
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n the call to SETADC, nchn is 1 or inc is 0, the single channel 


bit will be set in the mode word of the start RDA when the sweep start 


routi 


ne is called. 


SETADC can be invoked as a subroutine or a function as follows: 


or 


ibuf 


iflag 


ichn 


nchn 


inc 


ind 


21.3. 


initi 
routi 


CALL SETADC (ibuf,[{iflag],[ichn],[nchn],[inc],[ind] ) 


ind = ISTADC(ibuf,{iflag],[ichn],[{nchn], [inc], [ind] ) 


A 40-word array initialized by the SETIBF routine. 


Ignored. It is included for compatibility with K-series support 
routines. 


The first channel number. Default is 0. If ince equals 0O (or 
default), ichn is the address of a random channel list. A random 
channel list is an array of n elements, where each element is a 
channel number. The final element must have bit 15 set to 
indicate the end of the list. 


The number of samples to be taken per sequence. Default iS one 
sample. 


The channel increment. Default is 1. The user should specify an 
increment of 2 for differential A/D input. If inc equals 0, ichn 
is an array of random channels to receive input. 


Receives a success or failure code as follows: 


0 indicates an illegal channel number or SETIBF was. not 
called prior to the SETADC call. 


1 indicates successful recording of channel information for 
the sweep call. 


1.17 SETIBF: Set Array for Buffered Sweep - The SETIBF routine 
alizes an array required by buffered sweep routines. The SETIBF 
ne must be called before every call to a buffered sweep routine. 
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The SETIBF call is as follows: 


CALL SETIBF (ibuf,[ind],[lamskb] ,buf0[,bufl...buf7]) 


ibuf 


A 40-word array. 


ind 
Receives a success or failure code as follows: 
0 indicates a parameter or buffer error. 
1 indicates the array was successfully initialized. 
lamskb 
The name of a 4-word array. This array allows the use of 
multiple LPA11-Ks within the same program, since the LUN is 
specified in the first word of the array. Refer to the 
description of the LAMSKS routine. 
If compatibility with K-series software is desired, the default 
(LUN 7) lamskb parameter should be used, and LUN 7 will be 
asSigned to LAO: in the task-build command file for the user 
task. 
buf0, etc. 


The name of a buffer. A maximum of eight buffers can be 
specified. Any buffer names in excess of eight are ignored. At 
least two buffers must be specified to maintain continuous 
sampling. 


Each buffer specified in the call to SETIBF is assigned a number 
ranging from 0 to 7. 


The assignment of these numbers is based on the order in which buffer 
names appear in the argument list. The first buffer whose name 
appears in the list is assigned number 0, the second is assigned 
number 1, and so forth. In all subsequent calls to other routines 
involving the set of buffers specified in a call to SETIBF, these 
numbers, rather than names, are used to refer to particular buffers. 


21.3.1.18 STPSWP: Stop Sweep - The STPSWP routine stops a sweep that 
is in progress. 


The STPSWP call is as follows: 


CALL STPSWP (ibuf[,iwhen],[find]) 
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The 40-word array specified in the call that initiated a sweep. 


Specifies when to stop the sweep: 


0 stops the sweep, immediately aborting the sweep. This is 
the default stop method. The sweep will be stopped 
asynchronously by the LPA11-K hardware. When IOSB(1) 


equals 1, the sweep has been stopped. Call 


IWTBUF 


continously after calling STPSWP until the sweep has 
actually been stopped. When stopping (aborting) a sweep in 


this manner, the data contents of the current data 
cannot be guaranteed. 


+n (any positive value) stops the sweep at the end of 


buffer 


the 


current buffer. This is considered to be the normal means 


for stopping a sweep. 


-n (any negative value) is reserved. (Do not use.) 


Receives a success or failure code as follows: 


1 indicates that the sweep will be stopped (at the 
indicated by iwhen). 


0 indicates an illegal argument list. 


-n is a directive error code indicating that the stop 
OIO failed. 


time 


Sweep 


1.19 XRATE: Compute Clock Rate and Preset - The XRATE routine 
allows the user task to compute a clock rate and preset. The 
rate divided by the clock preset yields the desired dwell (intersample 


val). 


NOTE 


The XRATE routine can be used only on 
systems that have a FORTRAN or 
BASIC-PLUS-2 compiler. This module is 
not included with the other LPA11-K 
Support routines in object module 
format. Rather, it is included in 
source code format with the K-Sseries 
source modules in [45,10] on the system 
disk. 
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XRATE can be invoked as a subroutine or a function as follows: 


CALL XRATE (dwell,irate,iprset,iflag) 


or 
adwell = XRATE(dwell,irate,iprset,iflag) 
dwell 
The intersample time desired by the user. The time is expressed 
in decimal seconds (REAL*4). 
irate 
Receives the computed clock rate as a value from 1 to 5. 
iprset 
Receives the clock preset. 
iflag 
Specifies whether the computation is intended for Clock A or 
Clock B: 
0 indicates the computation is for Clock A. 
nonzero indicates the computation is for Clock B. 
adwell 


The actual dwell rate for the clock based on the irate and iprset 
parameters. 


21.3.2 MACRO-11 Interface 


The MACRO-11 interface to the LPA11-K consists of either the callable 
routines described in Section 21.3.1 or a set of device-specific QIO 
functions. 


21.3.2.1 Accessing Callable LPA11-K Support Routines - MACRO-11 
programmers access the LPA11-K support routines through either of two 
techniques: 


1. The standard subroutine linkage mechanism and the CALL op 
code 


2.  Special-purpose macros that generate an argument list and 
invoke a subroutine 


These techniques are described in the following subsections. 
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21.3.2.2 Standard Subroutine Linkage and CALL Op Code - LPA11-K 
routines can be accessed through use of the standard subroutine 
linkage mechanism and the CALL op code. The format of this procedure 
is: 


~-PSECT code 


MOV #arglist,R5 ;ARGUMENT ADDRESS TO R5 
CALL lsubr ;CALL LPA11-K ROUTINE 
-PSECT data 

arglist: .BYTE narg,0 ;NUMBER OF ARGUMENTS 
- WORD addri ;FIRST ARGUMENT ADDRESS 
- WORD addrn ; LAST ARGUMENT ADDRESS 


In this sample, the two PSECT directives are shown only to indicate 
the noncontiguity of the code and data portions of the linkage 
mechanism. Within the argument list, any argument that is to be 
defaulted must be represented by a -1l address (that is, 177777(8)). 


21.3.2.3 Special-Purpose Macros - To facilitate the calling of 
LPA11-K support routines from a MACRO-11 program, two macros are 
provided in file [45,10]LABMAC.MAC. These macros are: 

l. iINITS 

2. CALLS 


INITS is an initialization macro. It must be invoked at the beginning 
of the MACRO-11 source module. 


CALLS invokes an LPAl1-K support routine. The format of this macro 
call is as follows: 


CALLS lsubr,<argl,...,argn> 


lsubr 


The name of an LPA11-K support routine. 


argl, and so forth 


Arguments to be formatted into an argument list and passed to the 


routine, Each argument can be either a symbolic name or a 
constant (interpreted as a positive decimal number) or can _ be 
defaulted. 
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An example showing the use of these macros is as follows: 


~-TITLE EXAMPLE 
-IDENT /01.00/ 


IBUF: » BLKW 40. 
ISTAT: .BLKW 5 

INITS ; INITIALIZATION 
START: 


FIND STATUS OF 5 SWEEP BUFFERS 
BEING USED IN CURRENT SWEEP 


=e te NO fe 


CALLS IBFSTS (IBUF, ISTAT) 


- END START 
21.3.2.4 Device-Specific QIO Functions - Table 21-2 lists the 
device-specific functions of the QIO system directive macro that are 
available for the LPA11-K. Programmers uSing these functions are 


entirely responsible for buffer management (refer to Section 21.4) as 
well as all other interfaces (for example, the request descriptor 
array). Little (if any) performance improvement over the use of 
FORTRAN support routines can be expected by using QIOs. Therefore, it 
is recommended that routines described in Section 21.3.1 be used. 


Table 21-2 
Device-Specific QIO Functions for the LPA11-K 


IO0.CLK 


Start clock 


IO. INI Initialize LPA11-K 


IO. LOD Load microcode 


IO.STA Start data transfer 


IO.STP Stop request 
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The MACRO-11 programmer must set up the appropriate Request Descriptor 
Array (RDA) before the corresponding QIO request is issued. In the 
case of the IO.STA function (start data transfer), the RDA is set up 
with buffer virtual addresses. The LPAl11-K driver address checks and 
relocates these buffers, changing them from single-word to double-word 
addresses. The RDA is fully described in the source code of the 
driver. 


21.3.2.5 IO.CLK - The I0.CLK function writes an image into’ the 
LPAl1-K real-time clock control register and issues a clock start 
command. The format of the QIO request is: 


QIOSC IO.CLK,...,<mode,ckcsr,preset> 


mode 
The mode. 

ckesr 
The image to be written into the clock control register. To 
achieve the function of clock rate -l (see Section 21.3.1.2) for 
Clock A only, set a clock rate of 0 and set the Schmitt Trigger 1 
Interrupt Enable bit in the Clock A Status Register. 

preset 


The clock preset. 


21.3.2.6 IO.INI - The IO.INI function initializes the LPA11-K. The 
task issuing the QIO request must be privileged. The format of the 
request is as follows: 


OLOSC IO.,INL »s«.,<irbuft ;278.> 
irbuf 


A buffer containing an LPAl1-K initialize RDA. The buffer size 
must be at least 278 (10) bytes. 


21.3.2.7  I0.LOD —- The IO.LOD function loads a buffer of LPA1I]-K 


microcode. The issuing task must be privileged. The function 
verifies that there are no active users for the LPAl11-K and resets the 
hardware. It then loads and verifies the microcode, starts the 


LPA11-K, and enables interrupts. The function returns to the issuing 
task when the Ready Interrupt is posted. 
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The format of the QIO request for the IO.LOD function is as follows: 


OLOSC: 10. LOD;y.< <mbut, 2048. > 


mbuf 


A buffer containing microcode to be loaded. The buffer size must 
be 2048(10) bytes. 


21.3.2.8 I0O.STA - The IO.STA function issues an LPA11-K data transfer 
Start command. The format of the QIO request is: 


QIOSC IO.STA,...,<bufptr,40.> 


bufptr 


7 _ 1 eamnlea a nN 
A pointer to a buffer containing an LPA1I1-K sample start RDA. 


The buffer size must be at least 40(10) bytes. 


The subfunction codes defined for the IO.STA function are: 


Bit 0 = 0 indicates that an AST is to be generated for every 
buffer (if an AST is specified). 
Bit- 0 -= 1 indicates that an AST is to be generated only for 


exception conditions. 


21.3.2.9 I0O.STP - The IO.STP function stops a data transfer request. 
The issuing task must be the same task that initiated the data 
transfer. The format of the QIO request is as follows: 


QIOSC I0.STP,...,<userid> 


userid 


The index number associated with the user whose request is to be 
stopped. 


21.3.3 The I/O Status Block (IOSB) 


Each active sweep must have its own I/O status block. The I/O status 
block (IOSB) is a 2-word array allocated in the user program. It is 
used to receive the status of a call to an LPA1l1-K support’ routine. 
When a data sweep routine is called, the IOSB is always the first two 
words of the 40-word array specified as the first argument of the 
call. The first word of the IOSB contains the status code, and the 
second word contains the buffer size in words. 
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NOTE 


The 2-word IOSB is not directly used by 
the LPA1I-K driver. Instead, the driver 


uses a 4-word IOSB for internal 
communications with support routines; 
this 4-word IOSB is completely 


transparent to FORTRAN support routine 
users. However, when issuing QIOs, it 
is the 4-word IOSB that must be 
referenced. 


The first two words of the 4-word I0OSB 
function as a 2-word overall IOSB for 


returning QIO completion status. The 
driver returns status such aS _ sweep 
done, system errors, and LPA11-K 


hardware errors with this 2-word portion 
of the IOSB. 


The remaining two words function as an 
intermediate IOSB for passing status 
information during the data sweeps. 
MACRO-11 programs uSing QIO calls always 
receive the correct 2-word portion of 
the IOSB in the AST generated by the 
LPA11-K driver. 


The codes that can appear in the first word of an I/O status block are 
in ISA-compatible format (with the exception of the I/O pending 
condition). Table 21-3 lists all return codes (except 351; see 
Section 21.5). 


Table 21-3 
Contents of First Word of IOSB 


IOSB (1) Meaning 


FORTRAN | MACRO 


IO. PND Operation pending; I/0 in progress 
IS.SUC Successful completion 
IE.BAD Invalid arguments 


IE.IFC Invalid function code 


IE.DNR Device not ready (See Section 21.7) 


IE.VER Unrecoverable hardware error caused by 
power-fail 


IE.ULN LUN not assigned to LPA11-K 


(continued on next page) 
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Table 21-3 (Cont.) 
Contents of First Word of IOSB 


IOSB(1) Meaning 


FORTRAN | MACRO 


Illegal buffer specification 


Insufficient UMRs available for request 


3131 Data overrun 
3151 |IE.ABO Request terminated; LPAl1-K status code in 
IOSB (2) 
| 316 /IE. PRI Privilege violation 
3171 {IE.RSU Resource in use (load microcode only) 
320 IE.BLK Executive blocked driver waiting for UMRs 
325 IE.NOD System dynamic memory exhausted 


3591 IE.FHE Fatal hardware error on device 


IE.BCC LPA11-K load microcode error 


LE. TEE Invalid event flag specified 


1. IOSB(2) contains an LPA11-K status code. Refer to the LPAI11-K 
User's Manual for explanation of status code. 


21.4 BUFFER MANAGEMENT 


The management of buffers for data transfers by LPA11-K support 
routines involves the use of two FIFO (First-In, First-Out) queues: 


i. The device queue (DVQ) 
2. The user queue (USQ) 


The device queue (DVQ) contains the numbers of all buffers that the 
user task has released to the support routines in a call to RLSBUF. 
The buffers represented by these numbers are ready to be filled with 
data (input sweeps) or to be emptied of data (output Sweeps). Any 
buffer specified in a call to INXTBF must already be in DVOQ. 


The user queue (USQ) contains the numbers of buffers available to’ the 
user task. For output sweeps, this queue contains the numbers of 
buffers that have already been emptied by the driver. For input 
sweeps, the buffers represented by USQ are those which are filled with 
data. In both instances, the user task determines the next buffer to 
use (that is, it extracts the first element of USQ) by calling IGTBUF 


ms 
or IWTBUF. 


LABORATORY PERIPHERAL ACCELERATOR DRIVER 


Both the DVQ and USQ are initialized to -l -- indicating no 
buffers -- when the user task calls the SETIBF routine. The user task 
must call RLSBUF before initiating any sweep, since at least one 
buffer must be present in DVQ for the first input or output to occur. 


For input sweeps, it is recommended that the user task call RLSBUF, 
specifying the numbers associated with all the buffers to be used in 
the sweep. 


For output sweeps, the user task can specify two buffers (for 
continuous sweeps) in the call to RLSBUF. The first action then taken 
either in a completion routine or after a call to IWTBUF is to release 
the next buffer. However, note that this approach does not represent 
true multiple buffering since data overrun occurs if the second buffer 
is not released in time. 


If a buffer overrun occurs, the LPA11-K normally aborts the affected 
Sweep and returns an appropriate error code. However, the option of 
having buffer overruns treated as nonfatal error conditions can be 
selected by specifying the appropriate mode argument in any of the 
sweep calls. Then, when a buffer overrun occurs, the LPAI11-K 
automatically defaults to buffer 0 for its next data buffer. [In this 
case, the following special considerations regarding buffer management 
must be observed. 


Call RLSBUF before calling any of the sweep control calls. However, 
if buffer overruns are to be treated as nonfatal conditions, the task 
should not specify buffer 0 in the initial call to RLSBUF. (It is 
assumed at the outset that buffer 0 is available for use in this 
manner and, therefore, should not be released.) 


Once a buffer overrun has occurred, buffer 0 is used by the LPA11-K 
and placed on the user queue just like any other data buffer. At this 
point, buffer 0 is no longer available for buffer overruns. The task 
then removes buffer 0 from the user queue by IWTBUF or IGTBUF for 
possible processing. It is the task's responsibility to release 
buffer 0O for future buffer overruns by specifying buffer 0 in a call 
to RLSBUF. Note that the task cannot determine that buffer overrun 
occurred until it receives buffer 0 from IWTBUF or IGTBUF. 


The LPA11-K always uses buffer 0 following a buffer overrun if that 
condition was specified as nonfatal. Thus, when a second buffer 
overrun occurs before buffer 0 has been processed and made available 
for that purpose, a condition called "double buffer overrun" occurs. 
In this case, buffer 0 is not put on the user queue since the actual 
contents of buffer 0 cannot be determined at this time, and buffer 0 
may actually still be on that queue. The double buffer overrun 
condition is detected when the task attempts to make buffer 0 
available for future buffer overruns with the call to RLSBUF. Note 
that this is the first time that the task is notified of the 
condition. If a double buffer overrun condition is detected during 
the call to RLSBUF, the task must be notified of the condition 
indicating that the previous processing of buffer 0 contents may have 
been of no value (the LPA11-K probably changed the buffer's contents 
while it was being processed). 
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21.5 LOADING THE LPA-11 MICROCODE 


LAINIT is a privileged task that is used to load all versions of 
LPA11-K microcode. When called, LAINIT issues an IO.LOD function in a 
QIO request, followed-by IO.INI and I0O.CLK function requests. The 
IO.CLK function starts the clock with a default clock rate of 1 MHz. 


During SYSGEN Phase 1, a command file is generated with LPA11-K 
support selected through operator response to SYSGEN questions. 
During SYSGEN Phase 2, the command file builds LAINIT using additional 
information obtained through operator response to SYSGEN questions. 
This information further defines the LPA11-Ks system environment and 
characteristics for the specific user application. 


Separate tasks are built during SYSGEN that invoke LAINIT to _ load 
appropriate LPAl1-K microcode. These tasks are named LAINn, where n 
corresponds to unit number (starting with unit number 0) for each 
LPA1LI-K unit in the system. Thus, LAINIT is never directly invoked by 
the user. 

SYSGEN automatically generates command lines in SYSVMR.CMD that will 
install LAINIT and LAINO; LAINI1 and subsequent LPA11-K unit-numbered 
tasks are not automatically included in the command file. Thus, the 
user must install these tasks (if they are required) with VMR or MCR. 


Once LAINIT and LAINn tasks have been installed, a particular version 
of LPA11-K microcode for a specific unit can be loaded by running the 
corresponding LAINn task. For example: 


>RUN LAIN2 
executes LAIN2, loading microcode for LPA11-K unit 2. 


When a power-fail recovery occurs, the LPA11-K driver terminates all 
outstanding activity and requests execution of initiating task(s) 
(LAINn) for each unit. This automatically provides power-fail 
recovery for the LPA11-K microprocessor, provided the LAINIT and LAINn 
tasks are installed. Note that when either the RSX-11M system is 
bootstrapped or the LPA11-K driver is loaded, a simulated power-fail 
(resulting in driver power-fail recovery) occurs, loading microcode 
for each LPAI11-K unit. In addition, when the LPA11-K is brought 
online on an RSX-11M-PLUS system, a simulated power-fail occurs. 


If the request for the initiating task (LAINn) fails or the loader 
fails to load the driver, the LPA11-K unit does not become 
initialized. Any further attempt to use the LPAl11-K will fail, with 
the device not ready (IE.DNR) code returned to the requesting task. 


If there is no LPA-11K present at the default address, LAINx returns 
error code 351 in IOSB(1). This failure occurs if there is more than 
one LPA-11K and the one at the default address is removed. There must 
always be an LPA-11K at the default address. 
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All versions of LAINn set the real-time clock frequency to 1MHz by 


default. The UCB device characteristics word 4 (U.CW4) contains a 
16-bit buffer preset value that controls the rate of ticks (that is, 
the rate at which the clock interrupts). This value can be set 


dynamically or during SYSGEN. The quotient resulting when this value 
is divided into 1 MHz is the rate of ticks. For example, if U.cwW4 
contains 2, the tick rate is 500kHZ. The user can issue a Get LUN 
Information system directive to examine the preset value and the MCR 
SET /BUF command can be used to modify it while the system is running. 
This modification will take effect the next time the LPA11-K is 
reloaded with micro-code by LAINx. 


In order to attain maximum LPA11-K performance, the LPA11-K driver is 
designed to appear not busy to the RSX-11M/M-PLUS Executive. As a 
result, the potential problem exists that any privileged user can 
unload the driver while the LPA11-K is servicing other users. 
Therefore, the user must first determine that the LPA1l1-K is not being 
used prior to unloading the driver. 


21.7 TIME-OUT OF THE LPA11-K 


The error code IO.DNR means that the LPA11-K timed out while 
processing a user request. In dedicated mode, this condition can have 
special meaning. 


The LPA11-K driver (LADRV) disables the time-out countdown following 
LPAl11-K acknowledgement of the user-task request. In all cases in 
multirequest mode, and in most cases in dedicated mode, this 
acknowledgement is received almost immediately after the user-task 
request is passed to the LPA1l1-K. The only case when this is not true 
is when the user task requests that a data sweep be started while in 
dedicated mode. In this case, the LPAl11-K waits to transfer the first 
256 words of data before acknowledging the sweep request. 


If a task is sampling at extremely slow data rates in dedicated mode, 
the time to transfer that first 256 words may exceed the time-out 
count for the device. This can be avoided by using the multirequest 
mode. 


If a task must use dedicated mode for high sampling rates, and_ the 
start of the sweep will be delayed for an extended period of time, the 
time-out count for the LPA11-K must be disabled. (Refer to the note 
in LADRV describing this time-out problem and showing where the 
time-out can be safely disabled for sweep calls.) 


NOTE 
This procedure will disable the 


detection of real time-outs for sweep 
calls in dedicated mode. 


21-35 


LABORATORY PERIPHERAL ACCELERATOR DRIVER 


21.8 22-BIT ADDRESSING SUPPORT 


The LPA11-K driver supports 22-bit addressing on systems having that 
capability. When the system employs 22-bit addressing, certain 
restrictions are imposed. As a result, tasks written for use with 
earlier LPA11-K driver versions may not run without user’ task 
modifications. These restrictions are discussed in the remainder of 
this section. 


When the LPA11-K driver is executed on 22-bit systems, a certain 
contiguity of user-task data structures must be established. The task 
data transfer buffers and the IBUF array must be contiguous. In 
addition, the task random channel list (if present) and the last data 
transfer buffer must be contiguous. Thus, the correct sequence for 
user-task data is the IBUF array, followed by the task data transfer 
buffers, followed by the task random channel list. Failure to 
structure the user-task data in this manner can result in illegal 
buffer specification errors (IE.SPC) being returned or possible 
corruption of task address space by data sweeps. 


Since the LPA11-K user task can potentially request more buffer space 
than there is UMR mapping space, a limit on the total number of UMRs 
that can be used by the LPA11-K driver at any time must be specified. 
This limit is specified during SYSGEN part 1, along with the interrupt 
vector and CSR address for the LPAI11-K. 


If a task's UMR requirements will cause the total number of UMRs 
currently in use by the LPA11-K to exceed the SYSGEN-specified limit, 
the task will receive an Insufficient UMRs Available For Request 
(IE.DUN) error code in IOSB(1) of the IBUF array. 


This condition can be avoided by setting the UMR limit to the expected 
minimum number required for smooth LPA11-K operation for all expected 
users. Since each UMR maps 8K bytes, each user's requirements can be 
calculated as follows: 


e Each IBUF array requires 76(10) bytes of UMR mapping. 


e Add this result to the byte length of all the contiguous 
transfer buffers to be used in the sweep. 


e Add this result to the byte length of the random channel list 
(if it exists). 


e The number of UMRs the user task needs is the total byte count 
divided by 8192 (8K) and rounded up to the next 8K (if not an 
exact multiple of 8192). 


Because there are only 31 UMRs available for the entire system, it is 
not desirable to allow the LPA11-K driver (through the 
SYSGEN-specified limit) to have access to all or nearly all UMRS at 
any given time. Since other device drivers may also require UMR 
mapping, the total allocation of UMRs by LADRV can slowly choke a 
system, and for that reason allocation of UMRs must be carefully 
considered. 
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The UMR allocation limit for the LPA11-K can be changed by directly 
modifying the value in the LPA11-K's UCB word U.LAUB; it is not 
necessary to do another SYSGEN. Use the OPEN command to access and 
change the limit to the new value. Possible values can range from 
0-31. Then, make the required change, UNLOAD, and then LOAD the 
LPA11-K driver. If the LPA11-K driver is resident, the value in 
U.LAUB+2 must also be changed to the new value. 


NOTE 


Be sure the LPA11-K is idle before 
attempting to access the UCB. 


It is possible for a condition to exist where there may not be enough 
UMRsS available for the Executive to allocate to the driver at the time 
the request is made, even if the number of UMRsS necessary to map _ the 
user task's request are within the SYSGEN-defined limit. When this 
happens, the Executive blocks the driver until its UMR request can be 
granted. Since this condition can introduce sweep timing errors, the 
current sweep is unconditionally aborted and an appropriate error code 
(IE.BLK) is returned to the task in IOSB(1). 


21.9 SAMPLE PROGRAMS 


€ LPA11-K SAMPLE PROGRAM 
C 
C SAMPLE SHOWS THE BASIC FLOW FOR PROGRAMMING THE LPA11-K IN A HIGHER 
C LEVEL LANGUAGE. IT IS EXPECTED THE USER WILL TEST IOSB RETURNS AND 
C ERROR INDICATORS (IND) AS NECESSARY. SYNCHRONOUS PROGRAM TERMINATION 
C IS SUGGESTED. NOTE: THIS SAMPLE PROGRAM WILL NOT EXECUTE CORRECTLY IN 
C 22-BIT MODE 
C 
e D/A DEDICATED MODE WITH CONTINUOUS SAMPLING 
@ 
C PROGRAM RUNS 3 LOOPS (BASED ON NCNT). ON FIRST LOOP, 
Cc STOPS SYNCHRONOUSLY AT END OF PRESENT BUFFER WHICH HAPPENS 
ec TO BE BUFFER #3 BEING FILLED FOR THE 2ND TIME. 
c THE 2ND LOOP TERMINATES ASYNCHRONOUSLY (IWHEN=0). 
EC THE 3RD LOOP TERMINATES ASYNCHRONOUSLY ALSO. 
Cc 
c 
DIMENSION IBUF(40) ,IOSB(2) ,NB(1024,8) 
EQUIVALENCE (IBUF(1),IOSB(1)) 
EQUIVALENCE (NO,NB(1,1)),(N1,NB(1,2)),(N2,NB(1,3)),(N3,NB(1,4)) 
EQUIVALENCE (N4,NB(1,5)),(N5,NB(1,6)),(N6,NB(1,7)),(N7,NB(1,8)) 
CALL CLOCKA (4,=1) 
IWHEN=1 
NCNT=0 
2 ICNT=1 
5 CALL SETIBF(IBUF,IND,,NO,N1,N2,N3) 
C 
C INITIALIZE BUFFERS TO ALL -2'S 
(e 


DO 10 J=1,8 

DO 10 K=1,1024 

NB(K,J)=-2 

CALL RLSBUF(IBUF,IND,1,2,3) 

CALL DASWP(IBUF,1024,,,,20) 

20 CALL IWTBUF(IBUF,20,IBUFNO) 
CALL RLSBUF (IBUF,IND, IBUFNO) 
WRITE (1,300) IBUFNO,IOSB(1),IOSB(2),ICNT 
IF (NCNT.EQ.3) GOTO 40 


k- 
© 
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IF (ICNT.EQ.6) GOTO 2 
ICNT=ICNT+1 
IF (ICNT.NE.4) GOTO 20 
CALL STPSWP (IBUF,IBUFNO) 
IWHEN=0 
NCNT=NCNT41 
GOTO 20 
40 CALL IGTBUF(IBUF, IBUFNO) 
WRITE (1,300) IBUFNO,IOSB(1),IOSB(2),ICNT 
300 FORMAT (3X,1I10,208,110) 
STOP 
END 


The following sample program will test the digital I/0 interface of 
the LPA11-K. It will execute correctly in 22-bit mode. 


PROGRAM TO TEST DIGITAL INPUT AND OUTPUT FOR LPA11-K 
DIGITAL EQUIPMENT CORPORATION 


THIS PROGRAM IS DESIGNED TO OUTPUT A DATA BUFFER TO THE LPA1]1-K 
DIGITAL I/O INTERFACE AND AT THE SAME INSTANT FOR EACH SAMPLE 
WORD READ THE RESULTS BACK. THE DATA BUFFERS ARE COMPARED TO 
MAKE SURE THE TRANSFER IS COMPLETED SUCCESSFULLY. 


KEKEKKK NOTEL #keRKK 

THIS PROGRAM WILL WORK IF AND ONLY IF THE DIGITAL I/0 
ODULE 

UNIT SPECIFIED HAS THE MAINTENANCE JUMPER "WRAP-AROUND" 
ABLE 

INSTALLED !!1!! 


RESERVE STORAGE FOR LPA11-K ROUTINES 
THIS PROGRAM WILL WORK IN 22-BIT MODE 


DATA BUFFERS 


AANAAARAAAARAAAABAAAAAANAAARAAANANA 


INTEGER*2 IBUFI(40) , INBUF(300,4) 
INTEGER*2 COMMI (1240) 
EQUIVALENCE (IBUFI (1) ,COMMI(1)) 
EQUIVALENCE (INBUF (1,1) ,COMMI(41)) 


INTEGER*2 IBUFO(40) ,OUTBUF(300,4) 
INTEGER*2 COMMO(1240) 

EQUIVALENCE (IBUFO(1) ,COMMO(1)) 
EQUIVALENCE (OUTBUF (1,1) ,COMMO(41)) 


C RESERVE STORAGE AND EQUIVALENCE FOR RSX I/O STATUS BLOCKS 
LOGICAL*1 INIOS(4) ,OUTIOS (4) 
EQUIVALENCE (IBUFO(1) ,OUTIOS(1)),(IBUFI(1),INIOS(1)) 


c 
C SET BUFFER SIZE TO USE FOR THIS REQUEST -—- MAXIMUM OF 300 
WITHOUT 
C CHANGING THE DIMENSION STATEMENTS. MUST BE EVEN! 
ISIZE=300 
.@ 
C INITIALIZE THE PASS COUNTER FOR THE LOOP 
IPASS=1 
c 
C SET LPA11-K LOGICAL UNIT NUMBER AND ASSIGN IT TO LAO: 
ILUN=7 
CALL ASSIGN(ILUN,'LA:',0,ISTAT) 
IF(ISTAT .~LT. 0)GO TO 100 
C 
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C INITIALIZE THE OUTPUT DATA BUFFER 
DO 2 J=1,4 
DO 2 I=1,ISIZE,2 
OUTBUF (I,J)="125252 
OUTBUF (I+1,J)="052525 
CONTINUE 


NOTHING HAPPENS WHEN WE INITIALIZE THE TWO SWEEPS. 
CALL CLOCKA(0,0,ISTAT,ILUN) 
IF(ISTAT .NE. 1)GO TO 110 


2 
Cc 
C STOP LPA11-K REAL TIME CLOCK "A" THIS WILL MAKE SURE THAT 
Cc 
5 


= 
C INITIALIZE THE INPUT DATA BUFFER. ASSUME THE LPA11-K DIGITAL 
C I/O INTERFACE IS CONFIGURED IN THE DATA LATCH MODE (AS OPPOSED 
C TO SENSE). THUS THE OUTPUT DATA BUFFER MUST CONTAIN A BIT 
CHANGE 
C FOR EVERY BIT POSITION IN SUCCEEDING DATA WORDS. 

DO. 10. J=1,4 

DO 10 I=1,ISIZE 

INBUF (I,J) =0 
0 CONTINUE 


INITIALIZE DIGITAL OUTPUT SWEEP. THIS MUST BE DONE BEFORE INIT 
OF DIGITAL INPUT SWEEP! THE LPAl11-K PROCESSES THE TRANSFER OF 
DATA IN THE ORDER OF THE SPECIFICATION OF THE SWEEPS. THUS WE 
WANT TO OUTPUT BEFORE WE INPUT. 

CALL 
SETIBF (IBUFO,ISTAT, ,OUTBUF (1,1) ,OUTBUF(1,2) ,OUTBUF(1,3), 
ut OUTBUF (1,4) ) 
IF(ISTAT .NE. 1)GO TO 120 


AANRAAH 


C 
C RELEASE BUFFER FOR OUTPUT SWEEP 
C ALL FOUR BUFFERS -- INDEXES 0,1,2,3 -- ARE RELEASED 
CALL RLSBUF(IBUFO, ISTAT,0,1,2,3) 
IF(ISTAT .NE. 1)GO TO 130 
Cc 
C "START" DIGITAL OUTPUT SWEEP. REMEMBER NOTHING WILL HAPPEN 
UNTIL 
C WE START THE REAL TIME CLOCK. THE LPA11-K WILL PROCESS THE 
REQUEST 
C AND BE ALREADY TO TRANSFER DATA WHEN WE RESUME THE CLOCK. 
C EVENT FLAG 14 IS SPECIFIED. A DIFFERENT EVENT FLAG MUST BE 
C SPECIFIED FOR THE DIGITAL INPUT SWEEP SO THE FORTRAN PROGRAM 
C CAN SYNCHRONIZE WITH TWO INDEPENDENT, ASYNCHRONOUS PROCESSES. 
CALL DOSWP(IBUFO, ISIZE,4,0,1,14, 30,0) 
Cc 
Cc 
C NOW INITIALIZE FOR DIGITAL INPUT SWEEP. THE SAMPLING 
PARAMETERS 
C MUST BE THE SAME FOR BOTH THE INPUT AND OUTPUT SWEEP. WE WANT 
C TO WRITE AND READ THE SAME DATA WORD AT THE SAME TIME. 
CALL 
SETIBF(IBUFI,ISTAT,,INBUF (1,1) ,INBUF(1,2),INBUF(1,3), 
1 INBUF (1,4) ) 
IF(ISTAT .NE. 1)GO TO 140 


one) 


RELEASE THE INPUT BUFFERS 
CALL RLSBUF(IBUFI,ISTAT,0,1,2,3) 
IF(ISTAT .NE. 1)GO TO 150 


Cc 

C "START DIGITAL OUTPUT SWEEP. AGAIN, NOTHING WILL HAPPEN UNTIL 
C WE RESUME THE LPA11-K REAL TIME CLOCK. 

C EVENT FLAG 15 IS SPECIFIED TO SEPARATE THE INPUT AND OUTPUT 


CALL DISWP(IBUFI,ISIZE,4,0,1,15,30,0) 
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C NOW FOR THE BIG EVENT! WE START THE CLOCK AND SEE WHAT HAPPENS. 
CALL CLOCKA(1,-150,ISTAT, ILUN) 
IF(ISTAT .NE. 1)GO TO 150 


C 
C 
C THE LPA11-K SHOULD NOW BEGIN TO TRANSFER DATA 
C FIRST WE WAIT FOR THE DIGITAL OUTPUT SWEEP TO FINISH. IT WAS 
C STARTED FIRST AND SHOULD FINISH FIRST. WE VERIFY THAT IT 
C FINISHES CORRECTLY OR CHECK FOR ERRORS. 
15 CALL IWTBUF (IBUFO,14,IBUFNO) 
Cc 
C IF BUFFER NUMBER IS -1, THEN ERROR 
C IF BUFFER NUMBER IS 0,1, OR 2, THEN CONTINUE 
C IF BUFFER NUMBER IS 3, THEN FINISHED 
IF(IBUFNO .LT. 0) GO TO 160 
C 
C NOW WAIT FOR THE DIGITAL INPUT SWEEP TO FINISH. THE SAME ERROR 
C CONDITIONS APPLY. 


CALL IWTBUF (IBUFI,15,IBUFNO) 
IF(IBUFNO .LT. 0)GO TO 170 
IF(IBUFNO .LE. 2)GO TO 15 


Cc 
C THE FACT THAT WE HAVE GOTTEN HERE SAYS THE LPA11-K HAS DONE ITS 
C THING. 
C CHECK THE INPUT DATA BUFFERS AGAINST THE OUTPUT DATA BUFFERS 
DO 20 J=1,4 
DO 20 I=1,ISIZE 
IF(INBUF(I,J) .NE. OUTBUF(I,J))GO TO i180 
20 CONTINUE 
G 


C SUCCESSFUL COMPLETION, LET EVERYONE KNOW. THEN GO BACK AND DO 
bal 


C AGAIN. 
WRITE (5,1000) IPASS 

1000 FORMAT(' REQUEST COMPLETE!',2X,16) 
I PASS=IPASS+1 
GO TO 5 

C 


C REPORT ANY ERRORS THAT HAVE BEEN UNCOVERED IN THE EXAMPLE. 
C 


100 WRITE(5,1010)ISTAT 

1010 FORMAT(//,' ERROR ASSIGNING LUN TO LPA11-K ple) 
CALL EXIT 

110 WRITE (5,1020) ISTAT 

1020 FORMAT (//,' ERROR STOPPING LPA11-K CLOCKA ru} 
CALL EXIT 

120 WRITE (5,1030) ISTAT 

1030 FORMAT (//,' ERROR FROM SETIBF - OUTPUT BUFFER ', 16) 
CALL EXIT 

130 WRITE(5,1040) ISTAT 

1040 FORMAT(//," ERROR FROM RLSBUF - OUTPUT BUFFER ',I6) 
CALL EXIT 

140 WRITE(5,1050) ISTAT 

1050 FORMAT(//,' ERROR FROM SETIBF - INPUT BUFFER Yy2 8) 
CALL EXIT 

150 WRITE (5,1060) ISTAT 

1060 FORMAT(//," ERROR FROM RLSBUF - INPUT BUFFER ', 16) 
CALL EXIT 

1606 WRITE (5,1070) IBUFNO, (OUTIOS (I) ,1=1,4) 

1070 FORMAT (//,' ERROR FROM DOSWP ',12,4(3X,04)) 


Cc 


C *** WARNING *** DISWP MIGHT STILL BE ACTIVE WHEN YOU EXIT 
C 


CALL EXIT 
70 WRITE (5,1080) IBUFNO, (INIOS (I) ,I=1, 4) 
1080 FORMAT(//,' ERROR FROM DISWP ',12,4(3X,04) ) 
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C 


C *** WARNING *** DOSWP MIGHT STILL BE ACTIVE WHEN YOU EXIT 
Cc 


CALL EXIT 

180 WRITE(5,1090)1I,J,OUTBUF (I,J) ,INBUF(I,J) 

1090 FORMAT(//,' *DATA ERROR* -— WORD # ',14,2X,14,4X,06,2X,06) 
CALL EXIT 
END 
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K-SERIES PERIPHERAL SUPPORT ROUTINES 


22.1 INTRODUCTION 

K-series laboratory peripheral modules are supported through a set of 
Pprogram-callable routines that are linked with the user's task at 
task-build time. These routines are highly modular. Therefore, a 
particular task contains only that code necessary for the facilities 
actually used. Additionally, the support routines perform input and 
output operations through the Connect’ to Interrupt Vector (CINTS) 
Executive directive. This directive allows the user's task to bypass 
normal QIO processing and perform I/O almost completely independent of 
the Executive. 

The following subsections briefly describe the kK-series laboratory 


peripherals, the features provided by the K-series support routines, 
and the generation and use of these routines. 


22.1.1 K-Series Laboratory Peripherals 


The K-series peripheral support routines provide single-user, 
task-level support for the following laboratory peripheral modules: 


e AA11-K D/A converter 

e@ AD11-K A/D converter 

e AM11-K multiple gain multiplexer 

e DR11-K digital I/O interface 

e kKW11-K dual programmable real-time clock 

e AAVI11-A D/A converter (LSI-11-bus-compatible) 

e ADV11-A A/D converter (LSI-11-bus-compatible) 

e DRV11 parallel line unit (LSI-11-bus-compatible) 


e KWV11-A programmable real-time clock (LSI-11-bus-compatible) 
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The maximum supported hardware configuration consists of one KW11-K 
and sixteen of each of the AA11-K, AD11-K (with optional AM11-K), and 
DR11-K modules. The minimum configuration, if synchronous Sweeps are 
desired, would be one KW11-K and any one of the three other modules. 
A single DR11-K supports nonclocked, interrupt-driven I/0 Sweeps or 
Single digital input or output. A Single AD11-K supports single-word 
A/D input and nonclocked, overflow-driven sampling (provided that the 
A/D conversion is started with the EXT start input on the AD11-K). An 
AA11-K supports burst mode output and scope control. 


22.1.1.1 AA11-K D/A Converter - The AAl1-K includes four 12-bit 
digital-to-analog converters (DACs) and an associated display control. 
The display control permits the user to display data in the form of a 
4096 x 4096 dot array. Under program control, a dot may be produced 
at any point in this array, and a series of these dots may be 
programmed sequentially to produce graphical output. The display 
control may output to chart or X/Y recorder or CRT display unit. 


The AAV11-A is an LSI-11-bus-compatible D/A converter with 
characteristics similar to those of the AA11-K. 


22.1.1.2 AD11-K A/D Converter - The AD11-K is a 12-bit successive 
approximation converter that enables the user to sample analog data at 
specified rates and to store the equivalent digital value for 
subsequent processing. The basic subsystem consists of an input 
multiplexer (switch-selectable between 16-channel single-ended or 
8-channel differential), sample-and-hold circuitry, and a 12-bit A/D 
converter. By changing jumpers, the analog inputs can be made bipolar 
or unipolar. 


The ADV11-A is an LSI-11-bus-compatible D/A converter with 
characteristics similar to those of the AD11-K. 


22.1.1.3 AM11-K Multiple Gain Multiplexer - The AM11-K is a 
multiplexer expander that supplements the 16-channel single-ended (8 
differential) analog input multiplexer in the AD11-K. The expansion 
is done in three independent groups on the AM11-K. Each group can be 
set to 16 single-ended or pseudo-differential or 8 differential input 
channels; each group can have a gain of 1, 4, 16, or 64 assigned to 
it by a switch in the amplifier. 


22.1.1.4 DR11-K Digital I/O Interface - The DR11-K is a 
general-purpose digital input/output interface capable of the parallel 
transfer of up to 16 bits of data, under program control, between a 
PDP-11 UNIBUS computer and an external device (or another DR11-K). 


The DRV1l1 is an LSI-ll-bus-compatible, general-purpose input/output 
interface with characteristics similar to those of the DR11-K. 
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22.1.1.5 KW11-K Dual Programmable Real-Time Clock - The KW11-K 
dual programmable real-time clock option used in PDP-11l 
computers. Features include: 

Clock A 

e 16-bit counter 

e 16-bit programmable preset/buffer register 

e Four modes of operation 

e Two external inputs (Schmitt triggers) 

e Eight clock rates, program selectable 

e Five clock frequencies, crystal controlled for accuracy 

e Processor actions synchronized to external events 

Clock B 

e 8-bit counter 

e 8-bit programmable preset register 

e Repeated interval mode of operation 

e One external input (Schmitt trigger) 

e Seven clock rates, program selectable 

e Five clock frequencies, crystal controlled for accuracy 


The KWV11-A is an  LSI-11-bus-compatible real-time clock 
characteristics similar to those of the KW11-K. 
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The RSX-11M program-callable K-series support routines provide the 
following features: 


Clock overflow or trigger-driven A/D sweep 

Clock overflow or interrupt-driven digital input sweep 
Clock overflow or interrupt-driven digital output sweep 
Clock overflow or burst mode D/A sweep 

Single digital input 

Single digital output 


Single A/D input 
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e Scope control 

e Histogram sampling 

e Schmitt Trigger simulation 

e Clock control 

e 16-bit software clock 

e A/D input to real number conversion 

e Buffer control 

Immediate digital input or output can be performed at any time. 
Multiple clock-driven sweeps can be initiated if this optional feature 
was selected during the K-series generation dialog (see Section 
po as re EO Such sweeps, however, are subject to the following 
restrictions: 

1. Regardless of the number of controllers present, there can be 
only one active A/D sweep at any point in time. The same 
restriction holds true for D/A sweeps. It is possible, 
however, to perform digital input and digital output sweeps 
Simultaneously, using the same DRI11-K, so long as this 
feature is selected during the generation dialog. 

2. There can be no conflict in clock rates among the sweeps. 


3. Only the first sweep can use the delay from start event. 


4. The interevent time data-gathering routine cannot run in 
parallel with any other clock-driven sweeps. 


22.1.3 Generation and Use of K-Series Routines 


To use K-series support routines, the user must do the following three 
things during SYSGEN: 


e Reserve necessary vector space. 


e Specify that the CINTS Executive directive is to be included 
in the system. 


e Specify that AST support is required. 


At a point in time subsequent to SYSGEN, the user follows particular 
procedures for the following: 


1. Generation of K-series support routines 
2. Program use of K-series routines 


These two procedures are detailed in the following subsections. 
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22.1.3.1 Generation of K-series Support Routines - An indirect com- 
mand file, similar to those used for SYSGEN itself, is used to 
generate the K-series support routine library and other necessary 
facilities. This command file is invoked by typing the following: 


>@£200,200]SGNKLAB 


The dialog initiated by this command determines’ .the device 
configuration of the subsystem, the maximum number of buffers that 
will be used on a per-Sweep basis, and the inclusion or omission of 
optional features such as multiple clock-driven sweeps and duplex 
digital I/O sweeps. 


After th 
Fol lawin 


bev ait 


is information has been obtained, the command file creates the 
g: 

1. A prefix file, [45,10]KPRE.MAC, for use during assembly of 
K-series support routines. 


2. A data base file, [45,10]KIODT.MAC, containing control blocks 
needed to support the devices. 


3. A common block file, [45,10]KCOM.MAC, that allows user’ tasks 
to access the I/0 page. This file is used only on mapped 
systems. 


4, On mapped systems only, two indirect command files: 


a. [45,24]KCOMBLD.CMD, which is a TKB build file for the 
common block 


b. [1,54] INSKCOM.CMD that is used to install the common 
block 


At the user's option, the K-series routines themselves can then be 
assembled and an object library created. The user can specify the 
name of this library or accept the following default file 
specification: 


LB: [1,1]KLABLIB.OLB 


22.1.3.2 Program Use of K-series Routines - The steps required for 
routine program use of K-series support routines are as follows: 


1. Compile or assemble the program. If the task will be 
overlaid, it is required that both the buffers used by the 
K-series support routines and the support routines themselves 
reside in the root section of the overlay structure. 


Pe Age 
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2s Invoke TKB: 


a. On mapped systems only, use the /PR:0 Switch to indicate 
that the task is privileged. 


b. Include the following indirect command among the 
responses to the TKB prompt: 


TKB>@[1,5x] LNK2KLAB 


where x is 0 for unmapped systems and 4 for mapped 
systems. 


c. On mapped systems only, enter the following indirect 
command in response to the prompt for options: 


ENTER OPTIONS 
@{1,54] LNK2KCOM 


Tip 


3. On mapped systems only, enter the following indirect command 
from a privileged terminal before executing the program: 


>@[1,54] INSKCOM 
The following is a complete example of the steps previously described: 


>F4P KTEST,KTEST/—-SP=KTEST 

>TKB 
TKB>KTEST/PR:0,KTEST/-SP=KTEST, [1,1] F4POTS/LB 
TKB>@[1,54] LNK2KLAB 

TKB>/ 

ENTER OPTIONS 

TKB>@[1,54] LNK2KCOM 


TBK>// 


22.2 THE PROGRAM INTERFACE 


A collection of program-callable subroutines provides access to the 
K-series laboratory peripherals. ‘The formats of these calls are fully 
documented here for FORTRAN programs. MACRO-11 programmers access 
these same Subroutines either through the standard subroutine linkage 
or through the use of two special-purpoSe macros. Both techniques are 
described in Section 22.2.2. Both FORTRAN and MACRO programs must 
contain at least one I/O Status Block (IOSB), described in Section 
22.2.3, for retrieval of status information. 
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22.2.1 FORTRAN Interface 


Table 22-1 lists the FORTRAN interface subroutines for accessing 
K-series laboratory peripherals. 


Table 22-1 
FORTRAN Subroutines for K-series Laboratory Peripherals 


ADINP Initiate single analog input 


ADSWP Initiate synchronous A/D sweep 

CLOCKA Set Clock A rate | 

CLOCKB Control Clock B | 

CVADF Convert A/D input to floating point 

DASWP Initiate synchronous D/A sweep 

DIGO Digital start event 

DINP Digital input 

DISWP Initiate synchronous digital input sweep 

DOSWP Initiate synchronous digital output sweep 

DOUT Digital output 
| FLT16 Convert unSigned integer to a real constant | 

GTHIST Gather interevent time data 

IBFSTS Get buffer status 

ICLOKB Read 16-bit clock 

IGTBUF Return buffer number 

INXTBF Set next buffer 

IWTBUF Wait for buffer 

RCLOKB Read 16-bit clock 

RLSBUF Release data buffer 

RMVBUF Remove buffer from device queue 

SCOPE Control scope 

SETADC Set channel information 

SETIBF Set array for buffered sweep 

STPSWP Stop sweep 
XRATE Compute clock rate and preset 
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The calling sequences of the routines listed in Table 22-1 are 
compatible with the routines for the LPA-1l, described in Chapter 21. 
The following subsections briefly describe the function and format of 
each FORTRAN subroutine call. 


22.2.1.1 ADINP: Initiate Single Analog Input - The ADINP routine 
obtains a single word as input from the A/D converter. 


ADINP can be invoked as a subroutine or a function as follows: 


CALL ADINP ([iflag],[ichan],ival) 


or 
ival=IADINP ({iflag],[ichan],[ival]) 
iflag 
The gain options: 
0 Absolute channel addressing (default). This is the only 
mode supported on the ADV11 (Q-bus). 
dl Sample at a gain of 1. In modes 1, 2, 3, 4, and 5 each 
AD11-K/AM11-K is treated as 16 channels with channels 
17-63 strapped to gains 4, 16, and 64. The 48 
multiplexer channels are selected by the software 
according to the gain specification. Mode values 1, 2, 
3, 4, and 5 are not supported on the ADV11 (Q-bus 
version). 
2 Sample at a gain of 4. 
3 Sample at a gain of 16. 
4 Sample at a gain of 64. 
5 Perform auto gain ranging. 
ichan 
Selects the channel to be sampled. The default is 0. 
ival 


Receives the sample. The gain bits will be inserted if iflag is 
nonzero. 


22.2.1.2 ADSWP: Initiate Synchronous A/D Sweep - The ADSWP routine 
initiates a synchronous A/D input sweep through an AD11-K (and, if 
present, the AM11-K). The analog input word placed in the user buffer 
consists of the 12 bits read from the A/D converter and (except when 
the mode parameter equals 0) the 2 gain bits read from the A/D status 
register. A value of 177776(8) is returned for A/D time-out. A valie 
of 177777(8) is returned on an A/D conversion error. Such errors are 
typically caused by conversions occurring too fast. 


22-8 


K-SERIES PERIPHERAL SUPPORT ROUTINES 


If differential input is desired, the channel increment must be set to 
2 by calling the SETADC routine. The default channel increment is 1 
(single-ended input). 


NOTE 


This routine will expect to have the STl_ 
OUT from the KW11-K or similar trigger 

jumpered to EXT START on the ADI11-K if 

mode 512 is desired. This also requires 

the A EVENT OUT from the KW11-K clock 

trigger jumpered to the KW overflow on 

the AD11-K if clock driven sweeps are 

desired. 


The format of the ADSWP call is as follows: 


ibuf 


lbuf 


nbuf 


mode 


CALL ADSWP (ibuf,lbuf,[{nbuf],[{mode],{iprset],[iefn],[ldelay], 
[ichn] , [nchn] ) 


A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (IOSB). 


The size in words of each data buffer. All data buffers must be 
equal in size and lbuf must be greater than 0. 


The number of buffers to be filled. If nbuf is omitted or set 
equal to 0, indefinite sampling occurs. The STPSWP routine 
terminates indefinite sampling. 


Sampling options. The default is 0. The mode bit values listed 
below that are preceded by a plus sign (+) are independent and 
can be ADDed or ORed together. Those values not preceded by a 
plus sign are mutually exclusive and only one such value can be 
used at a time. All bit values not listed below are reserved. 


The following values can be specified: 
0 Absolute channel addressing (default). This mode allows 
the user to directly access all 63 channels of an 


AD11-K/AM11-K combination. This is the only mode that 
is LPA-11 compatible. 
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1 Sample with a gain of 1. In modes 1, 2, 3, 4, and 5 
each AD11-K/AM11-K is treated as 16 channels with 
channels 17-63 strapped to gains 4, 16, and 64. The 48 
multiplexer channels are selected by the software 
according to the gain specification. Mode values 1, 2, 
3, 4, and 5 are not supported on the ADV11 (Q-bus 
version). 


2 Gain of 4. See also mode value l. 

3 Gain of 16. See also mode value l. 

4 Gain of 64. See also mode value l. 

5 Driver will perform auto-gain ranging to return the 


result with the most significance. Note that use of 
auto-gain ranging may require dual sampling and will 
impact performance. See also mode value l. 


7 Use user-supplied interrupt routine. The routine must 
be named .ADINU and must follow the interrupt service 
routine coding conventions used in this subsystem. 
Refer to the source module KADIN5.MAC for an example of 
an A/D interrupt routine. 


+256 External start (ST1). 


+512 Nonclock overflow sampling triggered by STi. 


iprset 


The clock preset. The clock rate divided by the clock preset 
value yields the clock overflow rate. The XRATE subroutine can 
be used to calculate a clock preset value. If the iprset 
argument is omitted from the ADSWP call, the user must specify a 
mode value of +512. Otherwise, an error status code of 301 
(invalid arguments) is returned into the IOSB. 


iefn 


The event flag (1-96), a completion routine, or 0. If 0O or 
defaulted, event flag 30 will be utilized for internal 
synchronization. If iefn is an event flag (1-96), the selected 
event flag is set as each buffer is filled. If iefn is greater 
than 96, it is considered to be a completion routine that will be 
called with a JSR PC. Such routines must return with an RTS PC 
(or a FORTRAN RETURN statement). Furthermore, FORTRAN completion 
routines must not do any I/O through the FORTRAN runtime system, 
Since this may cause unpredictable results or fatal task errors. 


If multiple sweeps are initiated, the user should. specify 
different event flags. Adherence to this limitation cannot be 
enforced by the software. 


ldelay 


The delay from the start event (ST1) until the first sample in 


: pera 
IRATE units. Default or O indicates no delay. 
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ichn 
The number of the first channel to be sampled. The default of 0 
applies only if ichn was not established in a prior call to the 
SETADC routine. 

nchn 


The number of channels to sample. The default is 1. nchn may be 
set up with the SETADC routine. All nchn channels will be 
sampled on one clock interrupt. 


22.2.1.3 CLOCKA: Set Clock A Rate - The CLOCKA routine sets the rate 
for Clock A. The format of the call to this routine is as follows: 


CALL CLOCKA (irate,iprset,{ind],[lun]) 


irate 


The clock rate. One of the following must be specified: 


0 Clock B overflow (not on Q-busS version) or no rate 
1 1 MHz 

2 100 KHz 

| 10 KHz 

4 1 KHz 

5 100 Hz 

6 Schmitt Trigger 1 

7 Line frequency 


iprset 


The clock preset. The clock rate divided by the clock preset 
value yields the clock overflow rate. The XRATE routine can be 
used to calculate a clock preset value. 


ind 
Receives a success or failure code as follows: 
0 indicates illegal arguments. 
ag indicates Clock A set to start when sweep requested. 
lun 


The logical unit number. Present for LPA-1l compatibility. 
Ignored by K-series software. 
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22.2.1.4 CLOCKB: Control Clock B - The CLOCKB routine gives the user 
control over the KW11-K Clock B, which is used to maintain a 16-bit 
software clock. This feature is not available on LSI-1ll-bus versions. 
The 16-bit clock is incremented once per Clock B interrupt. The 
maximum value of the clock is 65535. 


The format of the call to CLOCKB is as follows: 


CALL CLOCKB ([irate],[iprset],[mode],[ind],[lun]) 


irate 


The clock rate. When irate is nonzero, the clock is set’ running 
at the selected rate after the preset value specified by iprset 
is loaded. The 16-bit software clock is not altered by starting 
the clock. The initial value of the 16-bit clock is 0 when the 
program is loaded. 


When irate is 0, clock B is stopped but the 16-bit software clock 
is unaltered. 


When irate is defaulted, the 16-bit software clock is zeroed but 
clock B continues to run. 


The following are the acceptable values for irate: 


0 Stop Clock B 

1 1MHz 

2 100 KHz 

3 10 KHz 

4 1 KHz 

5 100 Hz 

6 Schmitt Trigger 3 
7 Line frequency 


iprset 


The count by which to divide clock rate to yield overflow rate. 
Overflow events can be used to maintain the 16-bit software clock 
and/or drive clock A. The default value is 1. The maximum 
practical overflow rate in interrupt mode is 10 KHz. The range 
of iprset is 1-255. The value in iprset can be established by 
use of the XRATE routine. 
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mode 
The options. Either of the following can be specified: 
0 indicates normal operations. This is the default. The 
16-bit software clock is updated on Clock B overflow. 
The overflow rate should not exceed 10KHz. The software 
does not check the overflow rate. 
i indicates Clock B operates in noninterrupt mode. The 
16-bit clock is not incremented or altered. This allows 
a greater than 10KHz pulse to be sent to clock A. 
ind 
Receives a success or failure code as follows: 
0 indicates a failure to Start Clock B. 
1 indicates Clock B started. 
lun 
The logical unit number. This argument is ignored by the 
K-series routines. It is present for LPA-11l compatibility. 
22.2.1.5 CVADF: Convert A/D Input to Floating Point - The CVADF 


routine converts an A/D input value to a floating-point number. The 
routine can be invoked as a subroutine or a function as follows: 


CALL CVADF (ival,val) 


or 
val = CVADF(ival) 

ival 
A value obtained from A/D input. Bits 12-15 are the gain. Bits 
0-11 represent the value. 

val 


(REAL*4) receives the converted value. 
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22.2.1.6 DASWP: Initiate Synchronous D/A Sweep - The DASWP routine 
initiates synchronous D/A output to an AA11-K. 
The format of the DASWP call is as follows: 


CALL DASWP (ibuf,lbuf,[{nbuf],[{mode],[iprset],[iefn],[{ldelay], 
{ichn] , [nchn] ) 


ibuf 
A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (IOSB). 

lbuf 
The size in words of each data buffer. 11 data buffers must be 
equal in size and lbuf must be greater than 0. 

nbuf 
The number of buffers to be emptied. If nbuf is omitted or set 
equal to 0, indefinite emptying occurs. The STPSWP routine 
terminates indefinite emptying. 

mode 


The start criteria. Except where noted, the plus sign (+) 
preceding mode bit values listed below indicates that they are 
independent and can be added or ORed together. All bit values 
not listed below are reserved. 


The following values can be specified: 
0 indicates immediate start. This is the default. 


1 indicates that a group of data words, whose number is 
specified by nchn, is preceded by a scope control word 
(refer to Section 22.2.1.22 for a description of scope 
control words). This bit setting is ignored if +512 is 
also specified. This feature is not included in the 
Q-bus (AAV11) version. 


The buffer size specified by lbuf must be a multiple of 
nchn+l words. The DASWP routine, however, does not 
enforce this restriction. 


2 sets the intensify bit after each pair of channels (nchn 
must be 2) have been output. This feature is supported 
on the Q-bus version only. It assumes that bit 0 of 
DAC3 on the AAV11 is connected to the intensify input on 
the oscilloscope. 


+256 indicates external start (ST1). 
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+512 indicates non-clock-overflow, non-interrupt-—driven 
output (burst mode). This value cannot be specified 
with either external start (+256) or a nonzero Idelay 
value. A completion routine must be specified if nbuf 
is greater than the number of buffers supplied or if 
continuous burst output is desired. If nbuf equals -l, 
burst mode must be stopped by calling STPSWP from. the 
completion routine. 


iprset 


iefn 


The clock preset. The clock rate divided by the clock preset 
value yields the clock overflow rate. The XRATE subroutine can 
be used to calculate a clock preset value. 

If the iprset argument is omitted, the user must specify a mode 
value of +512. Otherwise, an error status code of 301 (invalid 
arguments) is returned into the IOSB. 


An event flag number (from 1 to 96), or a completion routine, or 
0. If 0 or defaulted, event flag 30 is used for internal 
synchronization. If iefn is an event flag from 1 to 96, the 
selected event flag is set as each buffer is emptied. If iefn is 
greater than 96, it is considered a completion routine that will 
be called with a JSR PC. Such routines must return with an RTS 
PC instruction (or a FORTRAN RETURN’ statement). Furthermore, 
FORTRAN completion routines must not perform I/O through the 
FORTRAN run-time system since this may cause unpredictable 
results or fatal task errors. 


If multiple sweeps are initiated, the user should specify 
different event flags. This limitation cannot be enforced by the 
software. 


ldelay 


ichn 


nchn 


The delay from start event (ST1) until the first sample in irate 
units. Default or 0 indicates no delay. 


The first channel number. The default is 0. 


The number of channels. The default is 1. When nchn equals 2 
and mode does not contain +l, the size of data buffers specified 
in lbuf must be an even number. The software does not check this 
requirement. 
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22.2.1.7 DIGO: Digital Start Event - The DIGO routine allows the user 
to specify the digital input bits that, when set, will cause the 
Simulation of an external start event and the start of a pending 
sweep. 

The format of the call to DIGO is: 


CALL DIGO ([iunit], [mask], [kount] ) 


iunit 


The DR11-K unit number. The default is 0. 


mask 
A logical mask that specifies one or more start bits. If zero, a 
pending digital start event request is immediately cancelled. If 
defaulted, an STl event is immediately simulated and the current 
value of the 16-bit software clock is returned in kount, if 
specified. 


kount 


Receives the current value of the 16-bit software clock when’ the 
defaulting of mask causes the Simulation of an ST1 event. 


22.2.1.8 DINP: Digital Input - The DINP routine inputs a Single 
16-bit word from a DR11-K. Bits read as a 1, can be masked with a l, 
causing the clearing of the bit in the DR11-K input buffer. 


During the K-series routines generation dialog, it is possible to 
select one of two versions of the DINP routine: 


1. A slow version containing all functions described below 


2. A fast version that omits the functions provided by the mask, 
iosb, and input arguments 


The fast version of DINP can be invoked as a function (IDINP) only. 
The slow version of DINP can be invoked as a subroutine or a function. 
The formats of the invocations are as follows: 

CALL DINP ([iunit],[mask],iosb,input) 


or 


ind=IDINP(iunit, [mask] ,iosb, [input] ) 


iunit 


The DR11-K unit number. This argument is required for the fast 
version of DINP. For the slow version, the default is 0. 


K-SERIES PERIPHERAL SUPPORT ROUTINES 


mask 
The bit mask used to specify which input bits will be cleared in 
the digital input register. The default is 177777(8) indicating 
all bits will be cleared. 

iosb 
A 2-word I/O status block array (see Section 22.2.3). 

input 
Receives the data input from the DR11-K. 

ind 


Receives the data input from the DR11-K if DINP is invoked as a 
function. 


22.2.1.9 DISWP: Initiate Synchronous Digital Input Sweep - The DISWP 
routine initiates a synchronous digital input Sweep through a DR11-K. 


The format of the call to DISWP is: 


CALL DISWP (ibuf,lbuf,[{nbuf],[mode],[{iprset],{iefn],[ldelay], 


fiunit] ) 
ibuf 
A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (IOSB). 
lbuf 
The size in words of each data buffer. All data buffers must be 
equal in size and lbuf must be greater than 0. 
nbuf 


The number of buffers to be filled. If nbuf is 0 or defaulted, 
indefinite sampling occurs. The STPSWP routine is used to 
terminate indefinite sampling. 


mode The sampling options. The default is 0. The plus signs (+) 
preceding the mode bit values listed below indicate that they are 
independent and can be added or ORed together. 
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The following values can be specified: 


0 Single-word sample, immediate start. This is the 
default mode. 


+256 External start (ST1). 


+512 Nonclock overflow interrupt-driven input. External 
start and delay are illegal. 


+1024 Time-stamped sampling. The double word consists of one 
data word followed by the value of the 16-bit software 
clock at the time of the sample. This option is not 
available if the KW11i-K clock is not being used (for 
example, on the Q-—bus). 


iprset 


The clock preset. The clock rate divided by the clock preset 
value yields the clock overflow rate. The XRATE subroutine can 
be used to calculate a clock preset value. 


If the iprset argument is omitted, the user must specify a mode 
value of +512. Otherwise, an error status code of 301 (invalid 
arguments) is returned into the IOSB. 


iefn 


An event flag number (from 1 to 96), or a completion routine, or 
O's If 0O or defaulted, event flag 30 is used for internal 
synchronization. If iefn is an event flag from 1 to 96, the 
selected event flag is set as each buffer is filled. If iefn is 
greater than 96, it is considered a completion routine that will 
be called with a JSR PC. Such routines must return with an RTS 
PC instruction (or a FORTRAN RETURN’ statement). Furthermore, 
FORTRAN completion routines must not perform I/O through the 
FORTRAN run-time system since this may cause unpredictable 
results or fatal task errors. 


If multiple sweeps are initiated, the user’ shold specify 


different event flags. This limitation cannot be enforced by the 
software. 


ldelay 


The delay from start event (ST1) until the first sample in irate 
units. Default or 0 indicates no delay. 


iunit 


The DR11-K unit number. The default is 0. 
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1.10 DOSWP: Initiate Synchronous Digital Output Sweep - The 
routine initiates a synchronous digital output sweep through a 

K. 

ormat of the call to DOSWP is as follows: 


CALL DOSWP (ibuf,lbuf,[{nbuf],[{mode],[iprset],[{iefn],[ldelay], 
{iunit]) 


A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (IOSB). 


The size in words of each data buffer. All data buffers must be 
equal in size, and lbuf must be greater than 0. 


The number of buffers to be emptied. If nbuf is 0 or defaulted, 
indefinite emptying occurs. The STPSWP routine is used to 
terminate indefinite emptying. 


The start criteria. The default is 0. 


The following values can be specified in the high-order byte of 
mode: 


0 Immediate start. This is the default. 

+256 External event start (ST1l). 

+512 Nonclock overflow, interrupt-driven output. External 

start and delay are illegal. 

t 
The clock preset. The clock rate divided by the clock preset 
value yields the clock overflow rate. The XRATE subroutine can 
be used to calculate a clock preset value. 
If the iprset argument is omitted, the user must specify a mode 


value of +512. Otherwise, an error status code of 301 (invalid 
arguments) is returned into the IOSB. 
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iefn 


An event flag number (from 1 to 96), or a completion routine, or 
0. If 0 or defaulted, event flag 30 is used for internal 
synchronization. If iefn is an event flag from 1 to 96, the 
selected event flag is set as each buffer is emptied. If iefn is 
greater than 96, it is considered a completion routine that will 
be called with a JSR PC. Such routines must return with an RTS 
PC instruction (or a FORTRAN RETURN’ statement). Furthermore, 
FORTRAN completion routines must not perform I/O through the 
FORTRAN run-time system since this may cause unpredictable 
results or fatal task errors. 


If multiple sweeps are initiated, the user should. specify 
different event flags. This limitation cannot be enforced by the 
software. 

ldelay 
The delay from start event (ST1) until the first sample in irate 
units. Default or O indicates no delay. 

iunit 


The DR11-K unit number. The default is 0. 


22.2.1.11 DOUT: Digital Output - The DOUT routine outputs a_e single 
16-bit word to a DR11-K. Only those bits in the output word specified 
by corresponding ones in a mask field are altered. 


During the K-series routines generation dialog, it is possible to 
select one of two versions of the DOUT routine: 


1. A slow version containing all functions described below 


2. A fast version that omits the functions provided by the mask 
and iosb arguments 


The slow version of DOUT can be invoked as a subroutine or a function. 
The fast version of DOUT can be invoked as a subroutine only. The 
formats of the invocations are as follows: 


CALL DOUT ([{iunit],[{mask] ,iosb,idata) 


or 

iout=IDOUT([iunit], [mask] ,iosb,idata) 
iunit 

The DR11-K unit number. The default is 0. 
mask 


Used to select which bits can be altered. The default is 
177777(8), indicating all bits. 
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iosb 
A 2-word I/O status block (see Section 22.2.3). 

idata 
The 16-bit output value for the DR11-K. A 1 sets a corresponding 
bit. A 0 clears the corresponding bit. 

iout 


Receives a copy of the DR11-K output register after it has _ been 
aitered. 


22.2.1.1 FLT16: Convert Unsigned Integer to a Real Constant - The 
FLT16 routine converts an unsigned 16-bit integer to a real constant 
(REAL*4). It can be invoked as a subroutine or a function as follows: 


CALL FLT16 (ival,val) 


or 

val=FLT16(ival[,val]) 
ival 

An unsigned 16-bit integer. 
val 


The converted (REAL*4) value. 


22.2.1.13 GTHIST: Gather Interevent Time Data - The GTHIST routine 
initiates sampling to measure the elapsed time between events. The 
value of the Clock A buffer/preset register at the time of ST2 firing 
is stored in a user-provided buffer. 

GTHIST is an optional facility that must be explicitly selected during 
the K-series generation dialog prior to its use in any program. The 
format of the call to GTHIST is as follows: 


CALL GTHIST (ibuf,lbuf,[nbuf],[mode],[{iprset],[iefn],[kount] ) 


ibuf 


A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (IOSB). 


lbuf 


The size in words of each data buffer. All data buffers must be 
equal in size and lbuf must be greater than 0. 
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nbuf 


The number of buffers to be filled. If nbuf is 0 or defaulted, 
indefinite sampling occurs. The STPSWP routine is’ used to 
terminate indefinite sampling. 


mode 
The sampling options as follows: 


0 indicates external event timing without Zero Base. This 
is the default. 


1 indicates external event timing with Zero Base. This is 
the only mode supported for the KWV11. 


iprset 


A null argument. It is present only to maintain compatibility 
with other sweep routine calling sequences. 


iefn 


An event flag number (from 1 to 96), or a completion routine, or 
0. If 0 or defaulted, event flag 30 is used for internal 
synchronization. If iefn is an event flag from 1 to 96, the 
selected event flag is set as each buffer is filled. If iefn is 
greater than 96, it is considered a completion routine that will 
be called with a JSR PC. Such routines must return with an RTS 
PC instruction (or a FORTRAN RETURN’ statement). Furthermore, 
FORTRAN completion routines must not perform I/O through the 
FORTRAN run-time system since this may cause unpredictable 
results or fatal task errors. 


If multiple sweeps are initiated, the user should specify 
different event flags. This limitation cannot be enforced by the 
software. 


kount 
A counter used by GTHIST, as described below. 


To take Post-Stimulus Time data, set mode to 0. STl1 signals’ the 
occurrence of a stimulus and starts the clock (that is, no data is 
taken until the first STl occurs). Each response is signalled by ST2, 
and the buffer/preset register contents are placed in the user buffer. 
Each STl resets the counter register to 0, and increments kount by 1. 
Thus, kount keeps track of the number of stimuli (ST1l events). Clock 
overflow stops the clock. The clock waits for the next STl event 
before restarting. The maximum stimulus-response interval is a 
function of the clock rate. 


To obtain Inter-Stimulus-Interval data, set mode to 1k. The time 
between succesSive events, as _ Signalled by ST2, is recorded. The 
maximum interevent time is a function of the clock rate. When clock 


overflow occurs, the value returned on the next ST2 firing is 
177777(8) and KOUNT is incremented. Thus, kount represents the number 
of times the maximum interevent time was exceeded. In general, the 
user Should ignore values of 177777(8). 
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22.2.1.14 IBFSTS: Get Buffer Status - The IBFSTS routine 
information on buffers being used in a sweep. 


The format of the call to IBFSTS is as follows: 


CALL IBFSTS (ibuf,istat) 


ibuf 


returns 


The 40-word array specified in the call that initiated a sweep. 


istat 


An array with as many elements as there are buffers involved in 
the sweep. The maximum is 8. IBFSTS fills each element in the 


array with the status of the corresponding buffer. The possible 
status codes are as follows: 
+2 indicates that the buffer is in the device queue. That 
is, it is waiting to be filled or emptied. 
+1 indicates that the buffer is in the user queue. That 


is, it is full of data (for input sweeps) or is waiting 


to be filled (for output sweeps). 


0 indicates that the status of the buffer is 


unknown. 


That is, it is not the current buffer nor is it in 


either the device or the user queue. 


-1 indicates that a service routine is currently using the 


buffer. 


22.2.1.15 ICLOKB: Read 16-bit Clock - The ICLOKB function returns the 
contents of the 16-bit software clock as an integer value to the user. 


The format of the ICLOKB function call is as follows: 


itim=ICLOKB (0) 


itim 
Receives the curent value of the 16-bit software clock 
unsigned integer. 
NOTE 
MACRO-11 programmers need not establish 
an argument block for the ICLOKB 


function. The current value of the 
software clock is returned in RO. 
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22.2.1.16 IGTBUF: Return Buffer Number - The IGTBUF routine returns 
the number of the next buffer to use. This routine should be called 
by user completion routines to determine the next buffer to access. 
It should not be used if an event flag was specified in the 
sweep-initiating call. Rather, the IWTBUF routine should be used with 
event flags. 


IGTBUF can be invoked as a subroutine or a function. The formats of 
the invocations are: 


CALL IGTBUF (ibuf,ibufno) 
or 


ibufno=IGTBUF (ibuf[,ibufno] ) 


ibuf 


The 40-word array specified in the call that initiated a sweep. 


ibufno 


Receives the number of the next buffer to access. If there is no 
buffer in the queue, ibufno contains -l. 


22.2.1.17 INXTBF: Set Next Buffer - The INXTBF routine alters’ the 
normal buffer selection algorithm. It allows the user to specify the 
number of the next buffer to be filled or emptied. 


INXTBF can be invoked as a subroutine or a function. The formats of 
the invocations are: 


CALL INXTBF (ibuf,ibufno[,ind]) 


or 
ind=INXTBF(ibuf ,ibufno[,ind]) 
ibuf 
The 40-word array specified in the call that initiated a sweep. 
ibufno 
The number of the next buffer the user wants filled or emptied. 
The buffer must already be in the device queue. 
ind 


Receives an indication of the result of the operation: 


0 indicates that the specified buffer was already active 
or waS not in the device queue. 


i indicates that the next buffer was successfully set. 
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22.2.1.18 IWTBUF: Wait for Buffer - The IWTBUF routine allows a user 
task to wait for the next buffer to fill or empty. It should be used 
in conjunction with the specification of an event flag in the 
sweep-initiating call. This routine should not be used if a 
completion routine was specified in the call to initiate a sweep. 
Rather, the IGTBUF routine should be used with completion routines. 


IWTBUF can be invoked as a Subroutine or a function. The formats of 
the invocations are as follows: 


CALL IWTBUF (ibuf,[iefn] ,ibufno) 


or 
ibufno=IWTBUF (ibuf,[iefn] ,[ibufno] ) 
ibuf 
The 40-word array specified in the call that initiated a sweep. 
iefn 
The event flag on which the task will wait. This should be _ the 
same event flag as that specified in the sweep-initiating call. 
If iefn equals 0 or is defaulted, event flag 30 is used. 
ibufno 


Receives the number of the next buffer to be filled or emptied by 
the user's task. 


22.2.1.19 RCLOKB: Read 16-bit Clock - The RCLOKB routine returns’ to 
the user's task the contents of the 16-bit software clock as a real 
constant. 
RCLOKB can be invoked aS a Subroutine or a function as follows: 

CALL RCLOKB (rlast,time) 


or 


time=RCLOKB(rlast,time) 


time 
Receives the current value of the 16-bit software clock as a real 
constant (REAL*4). 

rlast 


A value (REAL*¥4) to be subtracted from the current 16-bit 
software clock before it is returned into the time field. 
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22.2.1.20 RLSBUF: Release Data Buffer - The RLSBUF routine declares 
one or more buffers free for use by the interrupt service routine. 
The RLSBUF routine must be called to release buffer(s) to the device 
queue before the sweep is initiated. The device queue must always 
contain at least one buffer to maintain continuous sampling. 
Otherwise, buffer overrun occurs (see Section 22.3 for a discussion of 
buffer management). Note that RLSBUF does not verify whether’ the 
specified buffers are already in a queue. 
The format of the call to RLSBUF is as follows: 


CALL RLSBUF (ibuf,ind,n0O[,nl...,n7]) 


ibuf 


The 40-word array specified in the call that initiated a sweep. 


ind 
Receives a success or failure code as follows: 
0 indicates illegal buffer number specified. 


43 indicates buffer(s) successfully released. 


nO,nl,and so forth 


The numbers of buffers to be released. A maximum of eight can be 
specified. 


22.2.1.21 RMVBUF: Remove Buffer from Device Queue - The RMVBUF 
routine removes a buffer from the device queue. 


The format of the call to RMVBUF is as follows: 


CALL RMVBUF (ibuf,n[,ind] ) 


ibuf 


The 40-word array specified in the call that initiated a sweep. 


The number of the buffer to remove. 


ind 
Receives a success or failure code as follows: 


0 indicates that the specified buffer was not in _ the 
device queue. 


1 indicates that the specified buffer was removed from the 
queue. 
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22.2.1.23 SETADC: Set Channel Information - The SETADC routine 
establishes channel start and increment information for an A/D sweep. 
SETADC can be invoked as a subroutine or a function as follows: 


CALL SETADC (ibuf,[{iflag],[ichn],[(nchn],[inc],[ind]) 


or 
ind = ISTADC(ibuf,[iflag],[ichn],[{nchn],[inc], [ind] ) 

ibuf 
A 40-word array initialized by the SETIBF routine. 

iflag 
Equals zero if the user wants absolute addressing and nonzero for 
programmable gain addressing. The default is 0. 

ichn 
The first channel number. The default is 0. 

nchn 
The number of samples to be taken per interrupt. The default is 
1. 

inc 
The channel increment. The default is 1. The user. should 
specify an increment of 2 for differential A/D input. 

ind 


Receives a success or failure code as follows: 
0 indicates an illegal channel number. 


i indicates successful recording of channel information 
for an A/D Sweep. 


22.2.1.24 SETIBF: Set Array for Buffered Sweep - The SETIBF routine 
initializes an array required by buffered sweep routines. 


The format of the call to SETIBF is as follows: 


CALL SETIBF (ibuf,[ind],[{lamskb] ,buf0[,bufl...buf7]) 


ibuf 


A 40-word array. 
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ind 
Receives a success or failure code as follows: 
0 indicates an illegal number of buffers was specified. 
SETIBF initializes the array according to the maximum 
number of buffers allowed. This maximum number of 
buffers is specified by the user during the K-series 
generation dialog. 
1 indicates the array was successfully initialized. 
lamskb 
Present for compatibility with LPA-ll routines. It is ignored by 
K-series software. 
buf0, etc. 


The name of a buffer. A maximum of eight buffers can be 
specified. Any buffer names in excess of eight are ignored. At 
least two buffers must be specified to maintain continuous 
sampling. 


Each buffer specified in the call to SETIBF is assigned a number from 
0 to 7. 


The assignment of these numbers is based on the order in which buffer 
names appear in the argument list. The first buffer whose name 
appears in the list is assigned number 0, the second is assigned 
number 1, and so forth. In all subsequent calls to other K-series 
routines involving the set of buffers specified in a call to SETIBF, 


these numbers, rather than names, are used to refer to particular 
buffers. 


22.2.1.25 STPSWP: Stop Sweep - The STPSWP routine allows the user to 
stop a sweep that is in progress. 


The format of the call to STPSWP is as follows: 


CALL STPSWP (ibuf[,iwhen], [ind] ) 


ibuf 


The 40-word array specified in the call that initiated a sweep. 


iwhen 


Specifies when to stop the sweep: 


0 indicates at the next sample. This is the default. 

+n (any poSitive value) indicates at the end of the current 
buffer. 

-n (any negative value) is reserved. 
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ind 


Receives a success or failure code as follows: 


0 indicates that the sweep was not active or no 
could be found that was associated with the specified 
ibuf. 

1 indicates that the sweep will be stopped (at the 


indicated by iwhen). 


22.2.1.26 XRATE: Compute Clock Rate and Preset - The XRATE 


computes an appropriate clock rate and preset that will achieve a 


desired dwell (intersample interval). 


NOTE 
The XRATE routine can be used onl 
systems that have a FORTRAN or 
BASIC-PLUS-2 compiler. 


XRATE can be invoked as a subroutine or a function as follows: 


CALL XRATE (dwell,irate,iprset,iflag) 


or 
adwell = XRATE(dwell,irate,iprset,iflag) 
dwell 
The intersample time desired by the user. The time is expressed 
in decimal seconds (REAL*4). 
irate 
Receives the computed clock rate as a value from 1 to 5. 
iprset 
Receives the clock preset. 
iflag 
Specifies whether the computation is intended for Clock 
Clock B: 
0 indicates the computation is for Clock A. 
nonzero indicates the computation is for Clock B. 
adwell 


The actual dwell rate for the clock based on the irate and iprset 


parameters. 
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22.2.2 MACRO-11 Interface 


MACRO-11 programmers access the K-seriesS support routines described in 
Section 22.2.1 through either of two techniques: 


1. The standard subroutine linkage mechanism and the CALL op 
code 


2. Special-purpose macros that generate an argument list and 
invoke a subroutine 


These techniques are described in the following subsections. 


22.2.2.1 Standard Subroutine Linkage and CALL Op Code - K-series 
routines can be accessed through use of the standard subroutine 
linkage mechanism and the CALL op code. The format of this procedure 
is: 


~PSECT code 


MOV #arglist,R5 ;ARGUMENT ADDRESS TO R5 
CALL ksubr ;CALL K-SERIES ROUTINE 
~-PSECT data 

arglist: .BYTE narg,0 ;NUMBER OF ARGUMENTS 
«WORD addrl 7;FIRST ARGUMENT ADDRESS 
-WORD addrn ;LAST ARGUMENT ADDRESS 


In this sample, the two PSECT directives are shown only to indicate 
the noncontiguity of the code and data portions of the linkage 
mechanism. Within the argument list, any argument that is to be 
defaulted must be represented by a -1 (that is, 177777(8)). 


22.2.2.2 Special-Purpose Macros - To facilitate the calling of 
K-series support routines from a MACRO-11 program, two macros are 
provided in file [45,10]LABMAC.MAC. These macros are: 


dts INITS 
2% CALLS 
INITS is an initialization macro. It should be invoked at the 


beginning of the MACRO-11 source module. 


CALLS invokes a K-seriesS support routine. The format of this macro 
call is as follows: 


CALLS ksubr,ARG1,...,ARGN> 
ksubr 


The name of a K-series support routine. 


argl,etc. 


Arguments to be formatted into an argument list and passed to the 


routine. Fach argument can be either a symbolic name or a 
constant (interpreted as a positive decimal number) or can be 
defaulted. 
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22.2.3 The I/O Status Block (IOSB) 


Each active sweep must have its own I/O status block. The I/O status 
block (IOSB) is a 2-word array allocated in the user's program. It is 
used to receive the status of a call to a K-seriesS support routine. 
When a data sweep routine is called, the IOSB is always the first two 
words of the 40-word array specified as the first argument of the 
call. The first word of the IOSB contains the status code. The 
second word contains the buffer size in words. 


The codes that can appear in the first word of an I/O status block are 


in 1ISA-compatible format (with the exception of the I/0 pending 
condition). Table 22-3 lists all return codes. 


Table 22-3 
Contents of First Word of IOSB 


teeming 


Operation pending; 


IOSB word 1 


I/O in progress 


Successful completion 


Invalid arguments 


305 Hardware or software option not present 
306 Illegal buffer specification 
S13 Data overrun 


Request terminated 
Resource in use 


Invalid event flag 


22.3 BUFFER MANAGEMENT 


The management of buffers for data sweeps by K-series support routines 
involves the use of two FIFO (First-In, First-Out) queues: 


1. The device queue (DVQ) 

2. The user queue (USQ) 
The device queue (DVQ) contains the numbers of all buffers that the 
user has released to the support routines in a call to RLSBUF. The 
buffers represented by these numbers are ready to be filled with data 


(input sweeps) or to be emptied of data (output sweeps). Any buffer 
specified in a call to INXTBF must already be in DVQ. 
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The user queue (USQ) contains the numbers of buffers available to the 
user. For output sweeps, this queue contains the numbers of buffers 
that have already been emptied by the driver. For input sweeps, the 
buffers represented by USQ are those which are filled with data. in 
both instances, the user's task determines the next buffer to use 
(that is, extracts the first element of USQ) by calling IGTBUF or 
IWTBUF. 


Both the DVO and USQ are initialized to -1, indicating no buffers, 
when the user's task calls the SETIBF routine. The task must call 
RLSBUF before initiating any Sweep, since at least one buffer must be 
present in DVQ for the first input or output to occur. 


For input sweeps, the best strategy is to call RLSBUF, specifying the 
numbers associated with all the buffers to be used in the sweep. 


For output Sweeps, one approach is to specify two buffers (for 
continuous Sweeps) in the call to RLSBUF. The first action then taken 
either in a completion routine or after a call to IWTBUF would be to 
release the next buffer. Note, however, that this approach does not 
represent true multiple buffering, since data overrun occurs if the 
second buffer is not released in time. 


22.4 SAMPLE FORTRAN PROGRAMS 

Two sample FORTRAN programs showing the use of K-series support 
routines are presented in this section. The first program uses event 
flags for internal synchronization. The second program demonstrates 
the use of user-Supplied completion routine for synchronization. 


NOTE 


FORTRAN completion routines must not 
contain any of the following: 


e Any I/0 through the FORTRAN run-time 
system 


e Any use of virtual arrays 

e Any use of floating-point operations 

e Any errors, Since error reporting is 
done through the FORTRAN’ run-time 


system 


e Anything else that may change the 
FORTRAN impure area 


Any of the above may result in fatal task errors or unpredictable 
results. 
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22.4.1 Sample Program Using Event Flag 
IMPLICIT INTEGER (A-Z) 
DIMENSION BUF(1024,8), IBUF (40), IOSB(2) 
EQUIVALENCE (IBUF(1),IOSB(1)) 


INITIALIZE THE IBUF ARRAY FOR THE A/D SWEEP 


AAD 


CALL SETIBF (IBUF,IND, , BUF(1,1), BUF(1,2), BUF(1,3), 
* BUF(1,4), BUF(1,5), BUF(1,6), BUF(1,7), BUF(1,8)) 


WRITE (1, 900) 
READ (1, 910) IRATE, IPRSET 


SET THE CLOCK RATE AND PRESET FOR THE SWEEP 


QaAaAN 


CALL CLOCKA (IRATE, IPRSET, IND) 


THIS IS INPUT, SO RELEASE ALL BUFFERS TO SERVICE 
ROUTINE 


QAA-aAN 


CALL RLSBUF (IBUF,IND, 0,1,2,3,4,5,6,7) 


START THE SWEEP. USE 1024 WORD BUFFERS, SAMPLE 
FOREVER, EXTERNAL START, EVENT FLAG 30, 1 CHANNEL (0). 


QaAAAN 


CALL ADSWP (IBUF, 1024, -1, 256, IPRSET, 
* 30, 0, O, 1) 


HERE WE COULD CHECK THE I/O STATUS BLOCK TO ENSURE 
THAT THE SWEEP IS ACTUALLY RUNNING. 


QAAAA 


IBFCNT=0 


THIS IS THE TOP OF THE DATA PROCESSING LOOP. WE 
WAIT FOR A BUFFER TO BE COMPLETED, AND THEN DUMP 
THE FIRST 100 WORDS OF THE BUFFER TO LUN 1. 


AAAAN 


10 IBUFNO = IWTBUF(IBUF, 30)+1 


IWTBUF WILL RETURN A POSITIVE BUFFER NUMBER 
AS LONG AS THERE IS A BUFFER OF DATA AVAILABLE. 
IF IND IS -1, WE PROBABLY HAD DATA OVERRUN, SO STOP. 


AAQAAQAANA 


IF (IBUFNO .EQ. 0) STOP 
IBFCNT=IBFCNT+1 

WRITE (1,920) IBFCNT 

WRITE (1,930) (BUF(I,IBUFNO), I=1,100) 


RELEASE BUFFER FOR SERVICE ROUTINE TO REFILL 


aAaaAN 


CALL RLSBUF(IBUF,IND, IBUFNO-1) 
GOTO 10 
900 FORMAT (' ENTER IRATE, IPRSET:', $) 
910 FORMAT (I, 0) 
920 FORMAT (' DUMP OF BUFFER NUMBER ',I5,/) 
930 FORMAT (1X,1007) 


END 
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22.4.2 Sample Program Using Completion Routine 


aAaAN 


aaa 


AAAN 


A-~AAN 


QAaAAN 


10 


QAAAN 


900 
910 


AAAAAAANRAN 


IMPLICIT INTEGER (A-Z) 
EXTERNAL AST 


DIMENSION BUF(1024,8), IBUF (40), IOSB(2) 
COMMON /KDATA/ BUF, IBUF, IBFCNT 
EQUIVALENCE (IBUF(1),IOSB(1)) 


INITIALIZE THE IBUF ARRAY FOR THE A/D SWEEP 


CALL SETIBF (IBUF,IND, , BUF(1,1), BUF(1,2), BUF(1,3), 
* BUF(1,4), BUF(1,5), BUF(1,6), BUF(1,7), BUF(1,8)) 


WRITE (1, 900) 
READ (1, 910) IRATE, IPRSET 


SET THE CLOCK RATE AND PRESET FOR THE SWEEP 
CALL CLOCKA (IRATE, IPRSET, IND) 


THIS IS INPUT, SO RELEASE ALL BUFFERS TO SERVICE 
ROUTINE 


CALL RLSBUF (IBUF,IND, 0, 1, 2, 3, 4, 5, 6, 7) 


START THE SWEEP. USE 1024 WORD BUFFERS, SAMPLE 
FOREVER, EXTERNAL START, EVENT FLAG 30, 1 CHANNEL 


IBFCNT = 0 
CALL ADSWP (IBUF, 1024, 0, 256, IPRSET 
* AST, 0, 0, 1) 


‘ HERE WE COULD CHECK THE I/O STATUS BLOCK TO ENSURE 
THAT THE SWEEP IS ACTUALLY RUNNING. 


CALL WAITFR (23) 


WHEN EVENT FLAG 23 IS SET THE SWEEP IS COMPLETED. 
WE MAY EXIT NOW. 


STOP 


FORMAT (' ENTER IRATE, IPRSET:', $) 
FORMAT (I, 0) 

END 

SUBROUTINE AST 


THIS SUBROUTINE IS CALLED AT AST LEVEL WHENEVER 
A BUFFER IS COMPLETED. THIS ROUTINE PROCESSES 
THE CONTENTS OF THE BUFFER AND THEN RELEASES 
IT FOR THE SERVICE ROUTINE. IF THE SWEEP IS TO 
TERMINATE (IOSB NON-ZERO) THEN EVENT FLAG 23. IS 
SET TO INDICATE TO THE MAINLINE CODE THAT WE ARE 
DONE. 

IMPLICIT INTEGER (A-Z) 

DIMENSION BUF(1024,8), IBUF(40), IOSB(2) 

COMMON /KDATA/ BUF, IBUF, IBFCNT 

EQUIVALENCE (IBUF(1),IOSB(1)) 


IBUFNO = IGTBUF (IBUF) +1 


IF (IBUFNO-1) .GE. 0 GOTO 20 
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IF (IOSB(1) .EQ. 0) PAUSE ‘INCONSISTENT? 
CALL SETEF (23) 

RETURN 

IBFCNT = IBFCNT + 1 


HERE WE WOULD PROCESS THE DATA 


RELEASE BUFFER FOR SERVICE ROUTINE 


CALL RLSBUF (IBUF, IND, IBUFNO-1) 
RETURN 


END 
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22.2.1.22 SCOPE: Control Scope - The SCOPE routine allows the user to 
control the status register of an AAI11-K. 
The format of the call to SCOPE is as follows: 


CALL SCOPE (iunit,icntrl,iosb) 


iunit 


The AA11-K unit number. 


icntrl 
A combination of bit values as shown in Table 22-2. Any bits not 
listed in this table are cleared before output to the AA11-K 
status register 

iosb 
A 2-word I/O status block (see Section 22.2.3). 


Table 22-2 
Scope Control Word Values 


Erase storage CRT 


Set write-through mode 


Set store mode 


A digital signal available in 
the AA11-K. 


Intensify on X or Y 


Intensify on Y 


Intensify on X 


Fast intensify enable 


Intensify pulse 


The values in Table 22-2 are also used to create scope control words 
for calls to the DASWP routine with a mode value of l. 


22-27 


CHAPTER 23 


UNIBUS SWITCH DRIVER 


23.1 INTRODUCTION 


The UNIBUS switch driver supports DTO7 UNIBUS switch hardware on 
RSX-11M-PLUS systems. UNIBUS switches are electronic devices that 
allow peripherals to be switched from one CPU to another, enabling 
CPUS to share peripheral devices. UNIBUS switches also facilitate 
on-line system backup and allow dynamic reconfiguration of systems in 
which high availability of certain peripherals is required. 


23.1.1 DTO7 UNIBUS Switches 


DTO7 UNIBUS switches can provide two, three, or four ports’ for 
connecting an external UNIBUS run to one of two, three, or four CPUs. 


Any CPU can request connection to a UNIBUS run and receive the 
connection immediately if the requested UNIBUS run is in the neutral 
state (it is not connected to another CPU's UNIBUS). If the request 
is received when the UNIBUS run is connected to another CPU, an 
interrupt is generated, informing the connected CPU of the pending 
request, and a watchdog timer is started. The connected CPU normally 
acknowledges the request, indicating the UNIBUS is still in use. In 
this case, the UNIBUS remains connected to the CPU. However, if the 
CPU does not respond to the interrupt within the time limit imposed by 
the DT07's watchdog timer, the UNIBUS is switched to the requesting 
CPU. Thus, a CPU that is not operating remains connected to. the 
UNIBUS only until another CPU requests the UNIBUS. 


Each DT0O7 UNIBUS switch port functions as an isolation circuit. When 
its power is off, it does not affect any CPU operation. 


23.1.2 UNIBUS Switch Driver 


The UNIBUS switch driver permits the UNIBUS switch to be used in one 
of two ways: ; 


1. A CPU retains the UNIBUS until the task issuing the 
directives that connected the UNIBUS to this CPU exits. This 
is normally accomplished when the task attaches the UNIBUS 
Switch (IO.ATT function) and issues the connect function 
(IO0.CON). When the task exits (for any reason), the system 
detaches the UNIBUS switch (I0O.DET) and performs an implicit 
disconnect function (I0.DIS), releasing the UNIBUS switch for 
use by any other task. 
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The task that attaches the UNIBUS switch can be considered 
the manager of the UNIBUS switch until the task exits. The 
task can receive ASTs for certain conditions involving UNIBUS 
switching (see Section 23.3.1.1). 


2. A CPU retains the UNIBUS until a task is executed that 
explicitly disconnects the UNIBUS. This is normally 
accomplished when a task issues the IO.CON function and _ no 
previous IO.ATT was issued. Once the UNIBUS is connected, 
the task exits. The UNIBUS then remains connected until 
either the CPU fails to respond to other CPU requests for the 
UNIBUS, or a task is executed that explicitly disconnects the 
UNIBUS. Note that when operating in this manner, no active 
task is required in order to retain the UNIBUS. 


23.2 GET LUN INFORMATION MACRO 
Word 2 of the buffer filled by the Get LUN Information system 


directive (the first characteristics word) contains all Os. Words 3, 
4, and 5 are undefined. 


23.3 QI0 MACRO 


This section summarizes standard and device-specific QIO functions for 
UNIBUS switches. 


23.3.1 Standard QIO Functions 
Table 23-1 lists the standard functions of the QIO macro that are 
valid for UNIBUS switches. 


Table 23-1 
Standard QIO Functions for UNIBUS Switches 


QIOSC IOVATT, «3. 7<[ast]> ATTACH device 


QIOSC TOVDET “5% Detach device 


QIOSC TOeKE Ly vee Cancel I/O requests 


ast 


The address of an optional AST routine which will be entered if 
certain conditions are detected (see Section 23.3.1.1) 


IO.ATT does not connect the UNIBUS switch (See device-specific 
function IO.CON). 


JIBt $ 


IO.DET detaches the UNIBUS switch from the task. If the UNIBUS switch 
was previously attached by the IO.CON function, an implied disconnect 
(IO.DIS) function is performed. 
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The only I/O requests that can be affected by the IO.KIL function are 
IO.CON and I0.DPT. When IO.KIL is issued during an IO.CON function, 
further retries are canceled. When IO.KIL is issued during an I0.DPT 
function, the time-out count is changed, forcing time-out (IE.TMO) to 
occur. 


23.3.1.1 I0O.ATT - The IO.ATT QIO function attaches the UNIBUS' switch 
to the task issuing the QIO directive. An optional AST address 
parameter can be specified. However, if it is specified, it must 
remain valid while the UNIBUS switch remains attached to the task. 


The AST service routine for the UNIBUS switch is entered when one of 
the following conditions occur: 


e The UNIBUS switch has become connected to another CPU because: 


1. The operator manually switched the UNIBUS to another CPU, 
or 


2. This CPU failed to respond to another CPU's’ request for 
the UNIBUS within the specified time (the CPU must 
acknowledge the request by servicing an interrupt, as 
described in Section 23.1.1). 


UNIBUS switch condition code 1 is passed to the AST routine by 
the stack, indicating the cause of the AST. 


e The UNIBUS switch has disconnected from the CPU because: 


1. A power failure occurred in this CPU (system power 
failure) and the UNIBUS switch driver was unable to 
reconnect the bus, or 


2. A power failure occurred on the connected UNIBUS, causing 
the driver to automatically disconnect the UNIBUS 


UNIBUS switch condition code 2 (for a system power failure) or 
condition code 3 (for a UNIBUS power failure) is passed to the 
AST routine by the stack indicating the cause of the AST. 


23.3.1.2 IO.DET - The IO.DET function detaches the issuing task from 
the UNIBUS switch, and in addition, performs an implied disconnect for 
the issuing task if that task had connected the UNIBUS' switch. A 
detach function is generated by the Executive on behalf of an attached 
task if that task exits (normally'or abnormally) without explicitly 
detaching the device. For a Switched UNIBUS, this causes it to be 
disconnected if an attached, connected task faults in such a way as to 
cause it to exit. 


23.3.1.3 IO.KIL - The IO.KIL function will cancel any outstanding 
IO.CON function that has a nonzero retry count and any outstanding 
IO.DPT function that has not yet timed out. Other QIO functions in 
progress are not affected by IO.KIL, and are automatically completed. 
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23.3.2 Device-Specific QIO Functions 
The device-specific functions of the QIO macro that are valid for 
UNIBUS switches are shown in Table 23-2. 


Table 23-2 
Device-Specific QIO Functions for UNIBUS Switches 


Connect UNIBUS switch 


IO.CON,...,<[rent], [cpu] > 


IO.DIS,...,<[tout], [port] > 


Disconnect UNIBUS switch 


Disconnect UNIBUS switch 
| from specified CPU port 


IO.DPT,...,<[tout],{port]> 


Switch the UNIBUS from 
current CPU to specified CPU 


QIOSC IO.SWI,...,<cpu> 


Read UNIBUS switch CSR 


IO0.CSR,..- 


rent 
The number of additional times the connect will be attempted if 
the IO.CON fails to complete. 

cpu 
The ASCII letter designating the CPU to receive the UNIBUS 
switch. 

port 
The port number, ranging from 0 through 3, of the target CPU that 
must request the bus prior to the CPU that is currently connected 
to the UNIBUS actually completing the disconnect. The port 
number corresponds to the four MANUAL CONNECT switch positions 
(PORT 0 through PORT 3) marked on the DTO7 control panel. 

tout 


The maximum time (in Seconds) allowed (253. maximum) for the 
function to be completed before an error condition is reported. 


Parameter details are included in the following sections. 


23.3.2.1 I0.CON - The IO.CON (connect) function requests connection 
of a UNIBUS presently not connected to a specified CPU. It can be 
issued either by a task previously attached with the IO.ATT function 
or by a task that is not attached. The IO.CON function has four 
optional parameters. The use of each parameter is described as 
follows. 

Retry Count -- The retry count specifies the number of additional 
times the connect function will be attempted if the IO.CON fails to 
complete within the time-out period of the UNIBUS switch. Retry count 
parameters used in this manner are always nonzero positive values, 


23-4 


UNIBUS SWITCH DRIVER 


The IO.CON function is not completed until either the retry count 
expires or the UNIBUS switch is successfully connected. Thus, the 
issuing task having a nonzero retry count wil not be checkpointed 
until the IO.CON function is completed. 


When a retry count of 0 is specified, the connect function attempts to 
connect the UNIBUS switch once (no retries) and immediately reports 
the directive status to the issuing task. 


When a retry count of 177777 (-1) is specified, the connect function 
continues to retry the connection until a successful connection is 
made or an IO.KIL function is issued. 


CPU -- The CPU parameter can only be used with loosely coupled? 
multiprocessor systems to specify the CPU to which the UNIBUS switch 
should be connected. This function is used only when the UNIBUS 
switch is presently not connected (the IO.SWI function should be used 
to disconnect the UNIBUS switch from a connected closely coupled CPU 
and connect it to a specified closely coupled CPU). The CPU is 
specified by a single ASCII letter (A, B, C, or D). 


(23.3.2.2 IO.DIS - The IO.DIS function is used to disconnect the 
switched UNIBUS from the currently connected CPU. 


NOTE 


It is the responsibility of the task 
issuing the IO.DIS or IO.DPT function to 
determine that all devices on the 
switched UNIBUS are inactive when the 
function is issued. The UNIBUS' switch 
driver does not check for active devices 
on the UNIBUS before completing either. 
the IO.DIS or IO.DPT function. 


23.3.2.3 IO.DPT - The IO.DPT function is used in a_ loosely coupledl 
multiprocessor system to allow the UNIBUS to be connected to another 
CPU on a specified port if the CPU requests connection within a 
specified time interval. (Refer to the note at the end of Section 
235362525) 


Time-out -- The time-out parameter specifies the maximum time allowed 
for the function to complete before an error is reported. Time-out 
specifications are positive, nonzero values ranging from 1 to 254 
seconds. The default time-out value is 2 seconds. If the CPU 
parameter is included in the IO.DPT function, the driver waits for the 
specified CPU to request the UNIBUS up to the specified time-out 
value. If the CPU does not request the UNIBUS during this time, the 
UNIBUS remains connected and the IE.TMO status is returned to the 
issuing task. 


1. A loosely coupled system is one in which memory reSources are not 
shared by more than one CPU. 
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If a time-out value of 0 is specified, the IO.DIS function will not 
complete until either the successful disconnect occurs, or an IO.KIL 
function is issued. 


Port -- The port parameter can only be used with loosely coupled 
multiprocessor systems to specify the port through which the UNIBUS 
Switch should be connected to a CPU. The port is specified by a 
number ranging from 0 through 3. 


23.3.2.4 I0O.SWI - The IO.SWI function disconnects the UNIBUS switch 
from the currently connected CPU and connects it to the specified CPU 
in a closely coupled system. The CPU parameter is required. 


IO.SWI is executed without the possibility of a third CPU taking 
control of the UNIBUS during the switching process. 


The CPU parameter is used in closely coupled multiprocessor systems to 
specify the CPU to which the UNIBUS switch should be connected. The 
CPU is specified by a single ASCII letter (A, B, C, or D). 


23.3.2.5 I0.CSR - The IO.CSR function reads maintenance information 
contained in the device CSR and returns it in the second word of the 
I/O status block. Information returned is valid only if the UNIBUS 
switch is connected. The use of this function should be limited to 
diagnostic applications. 


23.4 POWER-FAIL RECOVERY 
23.4.1 System Power-Fail Recovery 


During power-fail recovery, the driver attempts to restore the _ state 
of the system prior to the actual power failure. If the UNIBUS switch 
is found to be disconnected during power-fail recovery, the driver 
attempts to reconnect the switched UNIBUS. If the first attempt to 
reconnect the UNIBUS is not successful, an entry is made in the error 
log and the attached task is notified of the UNIBUS switch state by 
the AST specified in the IO.ATT function (if previously issued). 


If an IO.CON function was in progress when the power failure occurred 
and a retry count was pending, the UNIBUS switch driver attempts to 
successfully connect the UNIBUS switch until the retry count expires. 


If an IO.DIS or I0.DPT function was in progress when the power failure 
occurred, the UNIBUS switch driver attempts to complete the operation. 


23.4.2 UNIBUS Power-Fail Recovery 


If an interrupt is received from the UNIBUS switch indicating a power 
failure has occurred on the switched UNIBUS, the driver issues an 
immediate disconnect (IO.DIS). The attached task (if any) is notified 
by the AST. Note that the system may be corrupted if some of the I/O 
devices on the switched UNIBUS were active when the power failure 
occurred, Since the drivers for those [I/0 devices may attempt to 
access the device registers after the switched UNIBUS (and I/0 
devices) has become disconnected. 
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23.5 STATUS RETURNS 


Table 23-3 lists the error and status conditions that are returned by 
the UNIBUS switch driver. 


Table 23-3 
UNIBUS Switch Driver Status Returns 


ee 


IS.SUC Successful completion 


The operation specified in the QIO directive was 
completed successfully. 

IS.PND I/O request pending 
The operation specified in the QIO directive has not 
yet been executed. The I/O status block is filled 
with Os. 

IE.ABO Request aborted 


An I/O request was queued (not yet acted upon by the 
driver) when an IO.KIL was issued. 


IE.BAD Bad parameters 
The parameters specified in the QIO macro were in 
error. 

IE.CNR Connect rejected 


The connect function did not successfully connect the 
switched UNIBUS to the specified CPU, and the retry 
count, if specified, has expired. 


IE.DAA Device already attached 


The device specified in an IO.ATT funcion was already 
attached by the issuing task. This code indicates 
that the issuing task has already attached the 
desired physical device unit, not that the unit was 
attached by another task. 


IE.DNA Device not attached 


The physical device unit specified in an I0.DET 
function was not attached by the issuing task. This 
code has no bearing on the attachment status of other 
tasks. 


LE thE Illegal function 


A function code was specified in an I/O request that 


is illegal for the UNIBUS switch driver. 
De a ee ee 


(continued on next page) 
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Table 23-3 (Cont.) 
UNIBUS Switch Driver Status Returns 


IE.NOD Insufficient buffer space 
Dynamic storage space has been depleted, resulting in 
insufficient buffer space available to allocate 
either the I/O packet or the device list buffer. 

IE.OFL Device off line 
The physical device unit associated with the LUN 
specified in the QIO directive (the UNIBUS switch) 
was not on line, or the CPU specified in the I0.CON 
or I0.SWI was not on line. 

IE.SPC Illegal address space 
The buffer specified in the IO.CON function was 
partially or totally outside the address space of the 
issuing task. 

IE.TMO Time-out error 


The time-out count expired during an IO.DPT operation 
before the target CPU requested the UNIBUS. This 
error code is also returned when the DT03/DT07 
hardware fails to respond to a request due to a 
hardware failure. 


23.6 FORTRAN USAGE 


All of the QIO functions described for the UNIBUS switch driver can be 
used in FORTRAN tasks, except AST support is not provided (IO.ATT 
function with an AST address specified). A macro subroutine can be 
written for the FORTRAN task to call that specifies the AST address. 


APPENDIX A 


SUMMARY OF I/O FUNCTIONS 


This appendix summarizes legal I/O functions for all device drivers 


described in this manual. Both devices and functions are listed 
alphabetically. The meanings of the five parameters represented by 
the ellipsis (...) are described in Section 1.5.1. The meanings of 


the function-specific parameters shown below are discussed in the 
appropriate driver chapters. The user may reference these functions 
symbolically by invoking the system macros FILIO$S (standard I/0 
functions) and SPCIOS (special I/O functions), or by allowing them to 
be defined at task-build time from the system object library. 


A.1 ANALOG-TO-DIGITAL CONVERTER DRIVERS 
LOE Kl pees Cancel I/O requests 


IO.RBC,...,<Stadd,size,stcnta> INITIATE an A/D conversion 


A.2 CARD READER DRIVER 


LOGATT psc Attach device 

LOSDET} 4.4% Detach device 

FOUKT Gigs 6% Cancel I/O requests 
IO.RDB,...,<stadd,size> READ logical block (binary) 
IO.RLB,...,<stadd,size> READ logical block (alphanumeric) 
IO.RVB,...,<Stadd,size> READ virtual block (alphanumeric) 


A.3 CASSETTE DRIVER 


TOMA Ppaes Attach device 

LO.DET 3 sare Detach device 

LODEOPR) «0s Write end-of-file gap 
TORIES 004 Cancel I/O requests 
IO.RLB,...,<Stadd,size> READ logical block 


SUMMARY OF I/O FUNCTIONS 


IO.RVB,...,<Stadd,size> READ virtual block 


IO.RWD,... Rewind tape 


10.SPB,...,<nbs> SPACE blocks 


IO.SPF,...,<nes> SPACE files 


IO.WLB,...,<stadd,size> WRITE logical block 


IO.WVB,...,<stadd,size> WRITE virtual block 


A.4 COMMUNICATION DRIVERS (MESSAGE-ORIENTED) 


LO.ATT 644 Attach device 


TO. DET j.6-2 Detach device 


TO. DR fie ws Set device to full-duplex mode 


TO.:HDX peas Set device to half-duplex mode 


TO SIN Li pices Initialize device and set device 
characteristics 


TO. Ki liy« «2 Cancel I/O requests 


IO.RLB,...,<stadd,size> READ logical block, stripping 
syne characters 


IO.RNS,...,<stadd,size> READ logical block, transparent mode 


IO.SYN,...,<syn> SPECIFY sync character 


IO.TRM,..-- Terminate communication, disconnecting 


from physical channel 
IO.WLB,...,<stadd,size> WRITE logical block with sync leader 
IO.WNS,...,<Sstadd,size> WRITE logical block, no sync leader 


A.5 DECTAPE DRIVER 


IO.RLB,...,<stadd,size,,,lbn> 
IO.RLV,...,<stadd,size,,,lbn> 
IO.RVB,...,<stadd,size,,,lbn> 
IO.WLB,...,<stadd,size,,,lbn> 
IO.WLV,...,<stadd,size,,,lbn> 


IO.WVB,...,<stadd,size,,,lbn> 


READ logical block (forward) 
READ logical block (reverse) 
READ virtual block (forward) 
WRITE logical block (forward) 
WRITE logical block (reverse) 


WRITE virtual block (forward) 


SUMMARY OF I/O FUNCTIONS 


A.6 DECTAPE II DRIVER 

TOSATT eé-< 

IO.DET,..- 

IO.KIL,.«. 
IO.RLB,...,<stadd,size,,,lbn> 
IO.WLB,...,<Sstadd,size,,,lbn> 
IO.WLC,...,<Sstadd,size,,,lbn> 
IO.RLC,...,<stadd,size,,,ibn> 
IO.BLS,...,<lbn> 


IO.DGN,... 


A.7 DISK DRIVER 


IO.RLB,...,<stadd,size,,blkh,blkl1> 


IO.RPB,...,<stadd,size,,,pbn> 


IO.RVB,...,<stadd,size,,blkh,blkl> 


IO.SEC,...,<stadd,size,pbn> 
IO.SMD,...,<density,,> 


IO.WDD,...,<stadd,size,,,pbn> 


IO.WLB,...,<stadd,size,,blkh,blkl1> 


IO.WLC,...,<stadd,size,,blkh,blkl> 


IO.WPB,...,<Stadd,size,,,pbn> 


IO.WVB,...,<stadd,size,,blkh,blkl1> 


A.8 GRAPHICS DISPLAY DRIVER 


LOVATT pedis 


IO.CON,...,<stadd,size,lpef,lpast> 


IO.CNT,... 


IO.DET,... 
I0.DIS,... 
IO.KIL,. . ed 


IO.STP,. ee 


Attach device 

Detach device 

Cancel I/O requests 

READ logical block 

WRITE logical block 

WRITE logical block with check 
READ logical block with check 
POSITION tape 


Run internal diagnostics 


READ logical block 

READ physical block 

READ virtual block 

SENSE characteristics (RX02) only 
SET media density (RX02 only) 


WRITE physical block orren 
deleted data mark) 


WRITE logical block 


WRITE logical block followed 
by write check 


WRITE physical block 


WRITE virtual block 


Attach device 
CONNECT to graphics device 


Continue (restart 
processing unit) 


display- 


Detach device 
Disconnect from graphics device 
Cancel I/O requests 


Stop (halt 
unit) 


display-processing 


A.9 


All I/0 functions listed below apply to the 


five 
by (D). 


TO. CCL ya ers 


IO.CTI, eee 


LO, CTY 5% ee 


I10.DCI. ee 


IO.DTI, eee 


LOsDTY +: ee 


IO.FLN,... 


IO.ITI,.. 


IO.LDI,... 


IO.LKE,... 


LOeLEly ss 


IO.LTY,. ee 


IO.MLO,.. 


IO.MSO,.. 


IO.NLK,.. 


TO NEN: Ses 
TOSRAD; <3. 
IO.RBC,... 
TO<SAO;0<.< 


LOUD ys us 
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INDUSTRIAL CONTROL SUBSYSTEMS 


,<stadd,sizb,tevf> 


,<stadd,sizb,tevf,arv> 


,<stadd,sizb,tevf> 


,<mn,ic> 


,<tname,[,tevf],pn,csm> 


,<tname,[{,tevf]> 
,<tname,[,tevf],cn[,arv]> 


,<tname,[{,tevf]> 


,<opn,pp,dp> 


,<opn,dp> 


,<tname> 


,<stadd> 
,<stadd,size,stcnta> 
,<chn,vout> 


,<tname> 


eu 
t 


Aang 


ICS/ICR subsystem. The 


functions supported by the DSS/DRS11 subsystem driver are marked 


CONNECT a buffer to digital 
interrupts 

CONNECT a_ buffer to counter 
interrupts 

CONNECT a buffer’ to terminal 
interrupts 

Disconnect a buffer from digital 
interrupts 

Disconnect a buffer from counter, 


interrupts 


Disconnect a buffer from terminal 


interrupts 
Set controller off line 
INITIALIZE a counter 


LINK task to 
(D) 


digital interrupts 


LINK task to error interrupts 


LINK task to counter interrupts 


LINK task to remote terminal 
interrupts 
OPEN or close bistable digital 


output points (D) 


PULSE single-shot digital 
points 


output 
UNLINK a task from all interrupts 
(D) 

Place ICR controller on line 

READ activating data (D) 

INITIATE multiple A/D conversions 
PERFORM analog output 


UNLINK a from 


interrupts 


task 
(D) 


digital 
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IO.UER,...,<tname> 


IO.UTI,...,<tname> 


IO.UTY,...,<tname> 


IO.WLB,...,<staddb,sizb> 


UNLINK a task from error 
interrupts 


UNLINK a task from counter 
interrupts 


UNLINK ae task from terminal 
interrupts 


TRANSMIT data to the ICR remote 
terminal 


A.10 LABORATORY PERIPHERAL ACCELERATOR DRIVER 


IO.CLK,...,<mode,ckcsr,preset> 


TOINT 24 ac p< 1 PbUE,279<> 
IO.LOD,...,<mbuf,2048.> 
IO.STA,...,<bufptr,40.> 


IO.STP,...,<userid> 


A.11 LABORATORY PERIPHERAL SYSTEMS DRIVERS 


IO.ADS,...,<stadd,size,pnt, 
ticks,bufs,chna> 


IO; HIS;.s6,;<Stadd,size,;pnt, 
ticks,bufs> 


IO.KIL,... 
IO.LED,...,<int,num> 


IO.MDA,...,<stadd,size,pnt, 
ticks ,bufs,chnd> 


IO.MDI,...,<stadd,size,pnt, 
ticks,bufs,mask> 


IO.MDO,...,<stadd,size,pnt, 
ticks,bufs,mask> 


TO. REL} «<.,<rel,pol> 
IO.SDI,...,<mask> 
I0.SDO,...,<mask,data> 


IO.STP,...,<stadd> 


PERFORM A/D sampling 
PERFORM histogram sampling 


Cancel I/O requests 
DISPLAY number in LED lights 


PERFORM D/A output 
PERFORM digital input sampling 
PERFORM digital output 


LATCH output relay 
READ digital input register 
WRITE digital output register 


STOP in-progress request 


SUMMARY OF I/O FUNCTIONS 


A.12 LINE PRINTER DRIVER 
LOCAL 9 eee 

LOVDET fs << 

IO.KIL,... 
IO.WLB,...,<stadd,size,vfc> 


IO.WVB,...,<stadd,size,vfce> 


A.13 MAGNETIC TAPE DRIVER 
POVALT pecs 

IO.DET,... 

BOW EOP: sca‘ 

TO. KI GL) sss 
IO.RLB,...,<stadd,size> 
IO.RLV,...,<stadd,size> 
IO.RVB,...,<stadd,size> 
IO.RWD,... 

IO.RWU,... 

EOcSEC yw. 
IO.SMO,...,<cb> 
IO.SPB,...,<nbs> 
IO.SPF,...,<nes> 
TO.STCy eae g<Cb> 
IO.WLB,...,<Sstadd,size> 


IO.WVB,..-,<stadd,size> 


A.14 PAPER TAPE READER/PUNCH 
IO.ATT,..- 
ITO.DET >, «ss 
IO.KIL,... 


IO.RLB,...,<stadd,size> 


Attach device 
Detach device 
Cancel I/O requests 
WRITE logical block 


WRITE virtual block 


Attach device 

Detach device 

Write end-of-file (tape mark) 
Cancel I/O requests 

READ logical block 

READ logical block reverse 
READ virtual block 

Rewind tape 

Rewind and turn unit off line 
Read tape characteristics 
MOUNT tape and set tape characteristics 
SPACE blocks 

SPACE files 

SET tape characteristics 
WRITE logical block 


WRITE virtual block 


DRIVERS 

Attach device 
Detach device 
Cancel I/O Requests 


READ logical biock (reader only) 


SUMMARY OF I/O FUNCTIONS 


IO.RVB,...,<stadd,size> READ virtual block (reader only) 
IO.WLB,...,<stadd,size> WRITE logical block (punch only) 
IO.WVB,...,<Sstadd,size> WRITE virtual block (punch only) 


A.15 PARALLEL COMMUNICATION LINK DRIVERS 
A.15.1 Transmitter Driver Functions 


IO.ATX,...,<stadd,size,flagwd, ATTEMPT message transmission 
id,retries,retadd> 


IO.STC,...,<stadd,size,[state] SET master section characteristics 
[mode], ,retadd> 


LOYSEC) 4i<5 Sense master section status 


A.15.2 Receiver Driver Functions 

LOCERK 0 04S CEES CORRECT for reception 
IO.ATF,...,<stadd,size,retadd> ACCEPT transfer 

LO, RPPs ¢e4 Reject transfer 


IO.DRX,... Disconnect from reception 


A.16 TERMINAL DRIVER 


IO.ATA,...,<ast[,parameter2] ATTACH device, specify unsolicited- 
[,ast2]> character AST1 


POAT Es se Attach device 


I0.CCO,...,<stadd,size,vfc> WRITE logical block, cancel CTRL/O 


LOGDET p04 Detach device 
SF.GMC,...,<stadd,size> GET multiple characteristics 
IO.GTS,...,<stadd,size> GET terminal support 
IO.HNG,... HANGUP remote line 

TO.R IT Gps x Cancel I/0 requests 


IO.RAL,...,<Stadd,size[,tmo]> READ logical block and pass all bits] 
IO.RLB,...,<stadd,size[,tmo]> READ logical blockl 


IO.RNE,...,<Stadd,size[,tmo]> READ logical block and do not echol 


1. “ast2", "parameter2", and "“tmo" parameters are available for 
full-duplex driver functions only. 
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SUMMARY OF I/0 FUNCTIONS 
IO.RPR,...,<stadd,size,[tmo], READ after promptl 
pradd,prsize,vfc> 
IO.RST,...,<stadd,size[{,tmo]> READ with special terminators 


IO.RTT,...,<stadd,size,[tmo], READ logical block ended by specified 
table> special terminator2 


IO.RVB,...,<stadd,size[,tmo]> READ virtual blockl 
SF.SMC,...,<stadd,size> SET multiple characteristics 
IO.WAL,...,<stadd,size,vfc> WRITE logical block and pass all bits 


IO.WBT,...,<stadd,size,vfc> WRITE logical block and break through 
any ongoing 1/0 


IO.WLB,...,<stadd,size,vfic> WRITE logical block 
IO.WVB,...,<stadd,size,vfc> WRITE virtual block 


Subfunction bits for terminal-driver functions: 


TF.AST Unsolicited-input-character AST 

TF.BIN Binary prompt 

TF .CCO Cancel CTRL/O 

TF.ESQ Recognize escape sequences 

TF.NOT Unsolicited input AST notification2 
TF.RAL Read, pass all bits 

TF.RCU Restore cursor position2 

TF.RNE Read with no echo 

TE.RST Read with special terminators 

TF .TMO Read with time-out2 

TF .WAL Write, pass all bits 

TF .WBT Break-through write 

TF.XCC CTRL/C starts a command line interpreter2 
TF .XOF Send XOFF 

1. “ast2", "parameter2", and "tmo" parameters are available for 


full-duplex driver functions only. 


2. Full-duplex driver only. 
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A.17 UNIBUS SWITCH DRIVER 


LO,ATT psc ees bast | > ATTACH device 

TO gE peeve Detach device 

tO. Ky ss Cancel I/O requests 
IO.CON,...,<[{rent],[cpu]> CONNECT UNIBUS switch 

OI1L0SC I0.DIS;.<«; Disconnect UNIBUS switch 

TO0.DPT ; «ss 9< [tout] ;[port) > DISCONNECT UNIBUS switch and connect 


to specified CPU port 


IO.SWI,...,<cpu> SWITCH UNIBUS from current CPU to 
specified CPU 


TO.CSR, Read UNIBUS switch CSR 


A.18 UNIVERSAL DIGITAL CONTROLLER DRIVER 


10, CCl jw.«.7<Stadd,Sizb,tevti> CONNECT a buffer to contact 
interrupts 


IO.CTI,...,<stadd,sizb,tevf,arv> CONNECT a buffer to timer 


interrupts 

LOC DCL ss ws Disconnect a buffer from contact 
interrupt 

LO.DEL p< 3% Disconnect a buffer from timer 
interrupts 

10.11 1).seeaXtingic> INITIALIZE a timer 

LOeR Lig ees Cancel I/O requests 

IO.MLO,...,<opn,pp,dp> OPEN or close latching digital 


output points 


IO.RBC,...,<stadd,size,stcnta> INITIATE multiple A/D conversions 


A.19 VIRTUAL TERMINAL DRIVER 


IO.ATT,...~ Attach device 
TO. DET seis Detach device 
TOn KE bg ee « Cancel I/0 request 
IO.RLB,...,<stadd,size> READ logical block 
IO.RVB,...,<Stadd,size> READ virtual block 


IO.WLB,...,<Sstadd,size,stat> WRITE logical block 
IO.WVB,...,<Stadd,size,stat> WRITE virtual block 
IO.STC,...,<cb,sw2,swl> SET terminal characteristics (enable/ 


disable intermediate buffering, or 
return I/O completion status) 
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APPENDIX B 


I/O FUNCTION AND STATUS CODES 


This appendix lists the numeric codes for all I/O functions, directive 
status returns, and I/O completion status’ returns. Lists are 
organized in the following sequence: 

e I/0 completion status codes 

e Directive status codes 

e Device-independent I/O function codes 


e Device-dependent I/O function codes 


Device-dependent function codes are listed by device. Both devices 
and codes are organized in alphabetical order. 


For each code, the symbolic name is listed in form IO.xxx, IE.xxx, or 
TSAXxX< A brief description of the error or function is also 
included. Both decimal and octal values are provided for all codes. 


B.1 I/0 STATUS CODES 


This section lists error and success codes which can be returned in 
the I/O status block on completion of an I/O function. The codes 
below may be referenced symbolically by invoking the system macro 
IOERRS. . 


B.1.1 I/O Status Error Codes 


Name Decimal Octal Meaning 

IE.ABO -15 177761 Operation aborted 

IE.ALN -34 177736 File already open 

IE.BAD -01 ue a i a a Bad parameter 

IE.BBE -56 177710 Bad block 

IE.BCC -66 177676 Block check error or framing error 


Name 
IE.BLK 
IE.BYT 
IE.CNR 
IE.CON 
IE.DAA 
IE.DAO 
IE.DNA 
IE.DNR 
IE.DUN 
IE.EOF 
IE. EOT 
IE. EOV 
IE.FHE 
IE.FLG 
IE.FLN 
IE. IEF 
IE.ITES 
IE.IFC 
IE.MOD 


IE.NLK 


IE.NLN 


IE.NOD 


IE.NST 


IE.NTR 


IE.OFL 


IE.ONP 


Decimal 


-20 


-19 


-73 


-22 


I/O FUNCTION AND STATUS CODES 


Octal 

177754 
LIT 9> 
177667 
T7752 
177770 
177763 
LITT 7A 
LITTTS 
177767 
177766 
177702 
177765 
177705 
177647 
177657 
177637 
177656 
177776 
177753 


177661 


177733 


LiTisl1 


177660 


177651 


177677 


L7TTTS 


Meaning 
Illegal block number 
Byte-ligned buffer specified 
Connection rejected 
UDC connect error 
Device already attached 
Data overrun 
Device not attached 
Device not ready 
Device not attachable 
End-of-file encountered 
End-of-tape encountered 
End-of-volume encountered 
Fatal hardware error 
Event flag already specified 
ICS/ICR controller already offline 
Invalid event flag 
Invalid escape sequence 
Illegal function 
Invalid UDC or ICS/ICR module 


Task not linked to specified 
ICS/ICR interrupts 


File not open 
No dynamic memory available to 
allocate a secondary control 


block 


Task specified in ICS/ICR Link or 
Unlink request not installed 


Task not triggered 
Device off line 


Illegal subfunction 


I/O FUNCTION AND STATUS CODES 


Name Decimal Octal Meaning 

IE.OVR -18 177756 Tllegal read overlay request 
IE.PES -83 177655 Partial escape sequence 
IE.PRI -16 177760 Privilege violation 

IE.REJ -88 177650 Transfer rejected 

IE.NOD -23 177751 No dynamic memory available 
IE.RSU -17 ee i a gs Nonsharable resource in use 
ITE.SPC -—06 LTI2 12 Illegal address space 
IE.TMO —-74 177666 Time-out error 

IE.VER -04 177774 Unrecoverable error 

IE.WCK -86 177652 Write check error 

IE.WLK -12 177764 Write-locked device 


B.1.2 I/0 Status Success Codes 


Decimal Octal 
Name Bytes Word Meaning 
IS.CR Byte 0: 1 006401 Successful completion with 
Byte 1: 15 carriage return 
IS.cc Byte 0: i 001401 Successful compietion on 
Byte l: 3 read terminated by CTRL/C 
IS.ESC Byte 0: 1 015401 Successful completion 
Byte l: 33 with ESCape 
IS.ESQ Byte 0: 1 115401 Successful completion with 
Byte l: 233 an escape sequence 
IS.PND +00 000000 I/O request pending 
IS.RDD +02 000002 Deleted data mark read 
IS.SUC +01 000001 Successful completion 
IS.TMO +02 000002 Successful completion on 
read terminated by time-out 
IS.TNC +02 000002 Successful transfer but 


message truncated (receiver 
buffer too small) 


I/O FUNCTION AND STATUS CODES 


B.2 DIRECTIVES CODES 
This section lists error and success codes that can be returned in the 


directive status word at symbolic location SDSW when a QIO directive 
is issued. 


B.2.1 Directive Error Codes 


Name Decimal Octal Meaning 

IE.ADP -98 177636 Invalid address 

TE.IEF -97 177637 Invalid event flag number 
IE.ILU -96 177640 Invalid logical unit number 
IE.SDP -99 L77635 Invalid DIC number or DPB size 
IE.ULN -05 177773 Unassigned LUN 

IE.UPN -O1 177777 Insufficient dynamic storage 


B.2.2 Directive Success Codes 
Name Decimal Octal Meaning 


IS.SUC +01 000001 Directive accepted 


B.3 I/O FUNCTION CODES 


This section lists octal codes for all standard and device-dependent 
I/O functions. 


B.3.1 Standard I/O Function Codes 


Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) Meaning 

IO.ATT 001400 3 0 Attach device 
IO.DET 002000 4 0 Detach device 
IO.KIL 000012 0 2 Cancel I/O requests 
I0.RLB 001000 2 0 Read logical block 
I0.RVB 010400 21 0 Read virtual block 
IO.WLB 000400 1 0 Write logical block 
IO.WVB 011000 22 0 Write virtual biock 
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B.3.2 Specific A/D Converter I/O Function Codes 

Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) 

IO.RBC 003000 6 0 


B.3.3 Specific Card Reader I/O Function Codes 


Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) 
IO0.RDB 001200 2 200 
B.3.4 Specific Cassette I/O Function Codes 
Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) 
I0.EOF 003000 6 0 
I0.RWD 002400 5 0 
I0.SPB 002420 5 20 
IO0.SPF 002440 5 40 


Meaning 


Initiate an A/D 
conversion 


Meaning 


Read logical block 
(binary) 


Meaning 


Write end-of-file 
gap 


Rewind tape 
Space blocks 


Space files 


B.3.5 Specific Communication (Message-Oriented) I/O Function Codes 


Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) 

IO. FDX 003020 6 20 
I0.HDX 003010 6 10 

IO. INL 002400 5 0 
IO.RNS 001020 2 20 
I0.SYN 003040 6 40 
IO.TRM 002410 5 10 
IO0.WNS 000420 il 20 


Meaning 


Set device to 
full-—duplex mode 


Set device to 
half-duplex mode 


Initialize device 
and set device 
characteristics 


Read logical block, 
transparent mode 


Specify sync 
character 


Terminate 
communication, 
disconnecting 
physical chann 


™m 


from 
el 


Write logical block 
with no sync leader 
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B.3.6 Specific DECtape I/O Function Codes 


Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) Meaning 
IO.RLV 001100 2 100 Read logical block 
(reverse) 
IO.WLV 000500 1 100 Write logical block 


(reverse) 


B.3.7 Specific DECtape II I/O Function Codes 


Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) Meaning 

IO.WLC 420 dL. 20 Write logical block 
with check 

TLOsRLC 1020 2 20 Read logical block 
with check 

IO.BLS 4010 10 10 Position tape 

I0.DGN 4150 10 150 Run internal 


diagnostics 


B.3.8 Specific Disk I/O Function Codes 


Symbolic Code Subcode ° 
Name Word Equivalent (High Byte) (Low Byte) Meaning 


IO.RPB 001040 2 40 Read physical block 
(RXO1, RLO1, RLO2 
only) 


IO.SEC 002520 5 120 Sense 
characteristics 
(RX02 only) 


IO.SMD 002500 5 100 Set media density 
(RX02 only) 


IO.WDD 001140 1 140 Write physical block 
with deleted data 
mark (RX02 only) 


IO.WLC 001020 1 20 Write logical block 
followed by write 
check (all except 
RX01, RX02) 


IO.WPB 000440 I 40 Write physical block 
(RXO1, RX02, RLOI, 
RLO2 only) 
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B.3.9 Specific Graphics Display I/O Function Codes 


Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) Meaning 

IO0.CON 015400 33 00 Connect to graphics 
device . 

IO.CNT 017000 36 00 Continue DPU 

IO, DIS 016000 34 00 Disconnect from 
graphics device 

IO0.STP 016400 35 00 Stop DPU 


B.3.10 Specific ICS/ICR, DSS/DR I/O Function Codes 


Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) Meaning 

IO.CCI 014000 30 0 Connect a buffer to 
digital interrupt 
input 

TO.2CTL 015400 33 0 ' Connect a counter 

IO.CTY 003400 7 0 Connect a remote 
terminal 

TO. DCT 014400 31 0 Disconnect a buffer 
from digital 
interrupt input 

IO.DTI 016000 34 0 Disconnect a buffer 
from counter input 

IO.DTY 006400 15 0 Disconnect a buffer 
from terminal input 

IO.FLN 012400 25 0 Place selected unit 
off line 

IO.ITI 017000 36 0 Initialize a counter 

IO.LDI 007000 16 0 Link a task to 
digital interrupts 

IO. LKE 012000 24 0) Link a task to error 
interrupts 

10.LTI 007400 17 0 Link a task to 
counter interrupts 

IO.LTY 010000 20 0 Link a task to 


terminal interrupts 
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Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) Meaning 

IO.MLO 006000 14 0 Open or close 
bistable digital 
output points 

IO.MSO 005000 r2 0 Pulse single-shot 
digital output 
points 

IO.NLK 011400 23 0 Unlink a task from 
all unsolicited 
interrupts 

IO.ONL 017400 37 0 Place selected unit 
on line 

IO.RAD 010400 21. 0 Read task activation 
data 

IO.RBC 003000 6 0 Initiate multiple 
A/D conversions 

IO.SAO 004000 10 0 Perform analog 
output to specified 
channel 

IO.UDI 011410 23 10 Unlink a task from 
digital interrupts 

IO.UER 011440 23 40 Unlink a task from 
error interrupts 

IO.UTI 011420 23 20 Unlink a task from 
counter interrupts 

LO.UTY 011430 23 30 Unlink a task from 
terminal interrupts 

IO.WLB 000400 1. 0 Output to remote 
terminal 

B.3.11 Specific LPA11-K I/O Function Codes 

Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) Meaning 

IO.CLK 015000 32 0 Start clock 

IO. INI 014400 34 0 Initialize LPA11-K 

IO. LOD 014000 30 0 Load microcode 

IO.STA 015400 9 1 Start transfer 

IO.STP 016400 35 0 Stop request 
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B.3.12 Specific LPS I/O Function Codes 


Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) Meaning 

IO.ADS 014000 30 0 Initialize A/D 
sampling 

IO.HIS 015000 32 0 Initialize histogram 
sampling 

I0.LED 012000 24 0 Display number in 
LED lights 

IO.MDA 016000 34 ) Initialize D/A 
output 

IO.MDI 014400 31 0 Initialize digital 
input sampling 

IO.MDO 015400 33 0 Initialize digital 
output 

IO.REL 013400 27 0 Latch output relay 

I0.SDI 013000 26 0 Read digital input 
register 

I0.SDO 012400 25 0 Write digital output 
register 

I0.STP 016400 BS) @) Stop in-progress 
request 

B.3.13 Specific Magtape I/O Function Codes 

Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) Meaning 

IO. EOF 003000 6 0 Write end-of-file 
gap 

IO.RLV 001100 2 100 Read logical block 
(reverse) 

IO. RWD 002400 5 0 Rewind tape 

IO. RWU 002540 5 140 Rewind and unload 

I0.SEC 002520 5 120 Sense 
characteristics 

I0.SMO 002560 5 160 Mount and set 
characteristics 

IO.SPB 002420 5 20 Space blocks 

1O.SPF 002440 5 40 Space files 

I0.STC 002500 5 100 Set characteristics 
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B.3.14 Specific Parallel Communications Link I/O Function Codes 


B.3.14.1 Transmitter Driver Functions - 


Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) Meaning 
IO. ATX 000400 il 0 Attempt message 
transmission 
I0.STC 002500 5 100 Set master section 
characteristics 
I0.SEC 002520 5 120 Sense master section 
status 
B.3.14.2 Receiver Driver Functions - 
Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) Meaning 
IO0.CRX 014400 31 0 Conneect for 
reception 
IO.ATF 001000 2 0 Accept transfer 
IO. RTF 015400 33 0 Reject transfer 
IO.DRX 001500 32 0 Disconnect from 
reception 


B.3.15 B.3.15 Specific Terminal I/O Function Codes 


Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) Meaning 

IO.ATA 001410 3 10 Attach device, 
specify 
unsolicited-input- 
character AST 

I0.CCO 000440 he 40 Write logical block 
and cancel CTRL/O 

SF .GMC 002560 5 160 Get multiple 
characteristics 

I0.GTS 002400 5 00 Get terminal support 

IO.HNG 003000 6 0 HANGUP remote line 

IO.RAL 001010 2 10 Read logical block 


and pass all bits 
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Symbolic Code Subcode 


Name Word Equivalent (High Byte) (Low Byte) Meaning 

IO.RNE 81620 2 26 Read with no echo 

IO.RPR GB44GO LL OTs) Read after prompt 

IO.RST GG1901 2 1 Read with special 
terminators 

lO. RTE 85881 V2 1 Read logical block 
ended by specified 
special terminator 
(Full-duplex driver 
only) 

SF.SMC GB244G 5 46 Set multiple 
characteristics 

IO.WAL 88419 1 18 Write logical block 
nd pass all bits 

IO.WBT GBB50G 1 19¢ Write logical block 


and break through 
on-going I/0 


Subfunction Bits: 


With IO.RLB, IO.RPR: 


TE.sRST a 
TF.BIN 2 
TF.RAL 18 
TF.RNE 26 
TF .XOF 166 
TE rho 288 


With IO.WLB: 


TF .WAL 19 
TF.CCO 4G 
TF .WBT 106 


With IO.ATT: 


TE AST 18 
TF.ESQ 20 
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B.3.16 Specific UDC I/O Function Codes 


Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) Meaning 
IO.CCI 014000 30 0 Connect a buffer to 
contact interrupt 
digital input 
IO.CTI 015400 33 0 Connect a timer 
I0.DCI 014400 31 0 Disconnect a buffer 
from contact 
interrupt digital 
input 
LO.DTI 016000 34 0 Disconnect a timer 
LO—% ETI 017000 36 0 Initialize a timer 
IO.MLO 006000 14 0 Open or close 
latching digital 
output points 
IO.RBC 003000 6 0 Initiate multiple 
A/D conversions 
B.3.17 Specific UNIBUS Switch I/O Function Codes 
Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) Meaning 
IO0.CON 15400 33 0 Connect UNIBUS 
switch 
LO. DIS 16000 34 0 Disconnect UNIBUS 
switch 
IO.DPT 16010 34 vie Disconnect UNIBUS 
switch and connect 
to specified CPU 
port 
IO.SWI 16400 35 0 Switch UNIBUS from 
current CPU to 
specified CPU 
IO.CSR 15000 32 0 Read UNIBUS switch 
CSR 
B.3.18 Specific Virtual Terminal I/O Function Codes 
Symbolic Code Subcode 
Name Word Equivalent (High Byte) (Low Byte) Meaning 
IO.STC 002500 5 100 Set terminal 
characteristics 
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QIO INTERFACE TO THE ACPS 


This appendix describes the QIO level interface to the file processors 
(ACPs). These include F1l1ACP for Files-1l1 disks and MTAACP for ANSI 
magnetic tape. 


F11ACP supports the following functions: 


IO.CRE Create file 

IO. DEL Delete file 

IO.ACR Access file for read only 

IO. ACW Access file for read/write 

IO.ACE Access file for read/write/extend 
IO.DAC Deaccess file 

10. EXT Extend file 


IO.RAT Read file attributes 
IO.WAT Write file attributes 


IO. FNA Find file name in directory 
IO.RNA Remove file name from directory 
IO. ENA Enter file name in directory 
IO.ULK Unlock block 


MTAACP supports the following functions: 


IO. FNA Find file by name 

IO. ENA Enter name in directory (a no-op) 
LO ,ACR Access for read only 

IO. ACW Access for read/write 

IO. ACE Access for read/write/extend 
IO. DAC Deaccess file 

IO. RVB Read virtual block 

IO.WVB Write virtual block 

TO. EXT Extend file 

IO.CRE Create file 

IO.RAT Read attributes 

IO.APC ACP control 

IO.APV Privileged ACP control 


C.1 QIO PARAMETER LIST FORMAT 


The device-independent part of a file processing QIO parameter list is 
identical to all other QIO parameter lists. The general QIO parameter 
lists is described in detail in Section 1.6 of this manual. The file 
processor QIOs require the following six additional words in the 
parameter jiists: 


Parameter Word 1 Address of a 3-word block containing the 
file identifier 
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Parameter Word 2 Address of the attribute list 
Parameter Words 3 & 4 Size and extend control information 
Parameter Word 5 Window size information and access 
control 
Parameter word 6 Address of the file name block 
NOTE 


The RSX-11M/M-PLUS Executive treats File 
Identifier Blocks, filename blocks, and 
attribute list entries as read/write 
data. For this reason, they may not be 
used in read-only code segments or 
libraries. 


C.1.1 File Identification Block 
The File Identification Block is a 3-word block containing the file 


number and the file sequence number. The format of the File 
Identification Block is shown in Figure C-l. 


File Number 


File Sequence Number 


Reserved 


Figure C-1 File Identification Block 


F11ACP uses the file number as an index to the file header in the 
index file. Each time a header block is used for a new file, the file 
sequence number is incremented. This insures that the file header is 
always unique. The third word is not currently used but is reserved 
for the future. 


C.1.2 The Attribute List 


The file attribute list controls FI1lACP reads or _ writes. File 
attributes are fields in the file header. These fields are described 
in detail in Appendix F of the IAS/RSX I/O Operations Reference 
Manual. 


The attribute list contains a variable number of entries terminated by 
an all-0 byte. The maximum number of entries in the attribute list is 
Six. 


An entry in the attribute list has the following format: 


~-BYTE <Attribute type>, Attribute size 
-WORD Pointer to the attribute buffer 
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C.1.2.1 The Attribute Type - This field identifies the individual 
attribute to be read or written. The sign of the attribute type code 
determines whether the transfer is a read or write operation. If the 
type code is negative, the ACP reads the attribute into the buffer. 
If the type code is positive, the ACP writes the attribute to the file 
header. Note that the sign of the type code must agree with the 
direction implied by the operation. For example, if the type code is 
positive, the operation must be an IO.WAT or IO.DAC. 


The attribute type is one of the following: 
e File owner (H.FOWN) 
The file owner UIC is a binary word. The low byte is’ the 
owner number and the high byte is the group number. 
e File protection (H.FPRO) 
The file protection word is a bit mask with the _ following 


format: 


Each of the fields contains four bits, as follows: 


Bit 1 Read Access 

Bit 2 Write Access 
Bit 3 Extend Access 
Bit 4 Delete Access 


e File characteristics (H.UCHA) 
The following user characteristics are currently contained in 
the 1-byte H.UCHA field: 


UC.CON 200 Logically contiguous file 
uC.DLK = 100 File improperly closed 


e Record I/O Area (U.UFAT) 
This field contains a copy of the first seven! words of the 
file descriptor block. See Appendix A of the IAS/RSX I/0 
Operations Reference Manual for a description of the FDB. 


e File name (I.FNAM) 
The file name is stored as nine Radix-50 characters. the 
fourth word of this block contains the file type and the fifth 
word contains the version number. 


e File type (I.FTYP) 
The file type is stored as three Radix-50 characters. 


e Version number (I.FVER) 
The version number is stored as a binary number. 


e Expiration date (I.EXDT) 

Creation date (I.CRDT) 

Revision date (I.RVDT) 

The expiration date is currently unused. When the file is 
created, the ACP initializes the creation date to the current 
date and time. It initializes the expiration and _ revision 
dates to 0. The ACP sets the revision date to the current 
date and time each time the file is deaccessed. 


1. RMS uses 32 bytes. The first seven are compatible with FCS for 
sequential files. 
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e Statistics block 
This block is described in Appendix H of the IAS/RSX I/0 
Operations Reference Manual. 


e Read entire file header 
This buffer is assumed to be 1000 blocks’ long. You cannot 
write this attribute. 


e Revision number (I.RVNO) 
The ACP sets the revision number to 0, and increments it every 
time the file is deaccessed. 


@e Placement Control 


C.1.2.2 Attribute Size - This word specifies the number of bytes of 
the attribute to be transferred. Legal values are from 1 to the 
maximum size of the particular attribute. Table C-1 shows the maximum 
size for each attribute type. 


Table C-l 
Maximum Size for Each File Attribute 


Maximum 
Attribute ttribute Attribute Size 
Type Code Type in Octal Bytes 


File owner 


Protection 


Placement control 16 


3 File characteristics | 2 | 
4 | Record I/O area | 40 | 
5 | File name,type,version number | 12 
6 | File type 4 | 
a | Version number | 2 | 
Expiration date 7 
Statistics block Ee ake 
Entire file header 0 
Block Size (magtape only) = 
Revision number and 
creation/revision/expiration dates 43 


(o} 
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C.1.2.3 Attribute Buffer Address - The attribute Buffer Address field 
contains the address of the buffer in the user's task space to or from 
which the attribute is to be transferred. 


C.1.3 Size and Extend Control 


These two parameters specify how many blocks the file processor 
allocated to a new file or adds to an existing file. These parameters 
also control the type of block allocation. 


The format is as follows: 


High 8 bits of size>, <extend control> 
w 16 bits of size> 


The size field specifies the number of blocks to be allocated to a 
file on I0.CRE and I0.EXT operations, and the final file size on 
IO.DEL operations. 


The extend control field controls the manner in which an extend 
Operation is to be done. The following bits are defined: 


EX.AC1=1 The extend size is to be added as a_ contiguous 
block. 

EX.AC2=2 Extend by the largest available contiguous piece up 
to the specified size. 

EX.FCO=4 The file must end up contiguous. 

EX. ADF=10 Use the default rather than the specified size. The 


default extend size is the size that was specified 
when the volume was mounted. 


EX.ALL=20 Placement control (see Section C.2). 


EX. ENA=200 Enable extend. 


C.1.4 Window Size and Access Control 


This parameter specifies the window size and access control 
information in the following format: 


-BYTE <window size>, <access control> 


This word is only processed if the high bit of the access control byte 
(AC.ENB) is set. 


Window size is the number of mapping entries. Specifying a negative 
window size minimizes window turns. If this byte is zero, the file 
processor uses the volume default. The size of the window allocated 
in the dynamic storage region is 6 times the number of mapping entries 


(each mapping entry is 3 words), plus 10 bytes for the window control 
block. 
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On RSX-1LIM-PLUS systems with secondary pool support, the mapping 
entries are allocated in secondary pool. The window control block and 
a pointer to secondary pool are located in primary pool. 


The following access control bits are defined: 


AC.LCK=1 Lock out further accesses for Write or Extend 

AC.DLK=2 Enable Deaccess lock 
The deaccess lock sets the lock bit in the file header 
if the file is deaccessed as the result of a_ task 
exit without explicitly deaccessing the file. The 
lock bit is set by the executive. The lock bit is not 
set when the system crashes. 


AC.LKL=4 Enable block locking 
AC.EXL=10 Enable explicit block unlocking 
AC. ENB=200 Enable Access 
AC. RWD=10 Rewind the volume (labeled and unlabeled magtape only) 
AC .UPD=100 Update mode (labeled magtape only) 
AC. POS=20 Do Not Position to end-of-volume (labeled magtape 
only) 
AC.WCK=40 Initiate driver write-checking 
NOTE 


Both AC.LKL and AC.EXL must be set if 
you want block locking. If you do not 
want block locking, both bits must be 
clear. Any other combination is an 
error. 


C.1.5 File Name Block Pointer 


This word contains the address of a 15-word block in the issuing 
task's space. This block is called the file name block. The file 
name block is described in detail in Appendix B of the IAS/RSX I/0 
Operations Reference Manual. 


The fields of the file name block that are particularly important in 
file-processing operations are: 


® Directory identification (N.DID) 
This field is required for all disk operations. It specifies 
the directory to which the operation applies. This field is 
not used for tape operations. 


@e File identification (N.FID) 
This field is required as input for enter operations. This 
field is returned as output by find and remove operations. 


@e File name (N.FNAM), type (N.FTYP), and version number (N.FVER) 
These fields are required as input to enter, find, and remove 
operations. For find and remove operations, the file 
processor locates the appropriate entry by matching the 
information in these fields with the directory entries. 


e Status word (N.STAT) 


@e Wildcard context (N.NEXT) 
This field is required as input for wildcard operations. It 
specifies the point at which to resume processing. It is 
updated for the next operation. It must initially be set to 
QO. 
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C.2 PLACEMENT CONTROL 


The placement control attribute list entry controls the placement of a 
file in a particular place on the disk. You can specify either exact 
Or approximate placement on IO.CRE and IO.EXT operations. 


The placement control entry must be the first entry in the attribute 
List, 


The format of the placement control attribute list entry is as 
follows: 


-BYTE placement control,0 

-WORD high-order bits of VBN or LBN 

-WORK low-order bits of VBN or LBN 

~-BLKW 4 ; Buffer to receive starting and ending LBN if 
AL.LBN is set. 


The following bits are defined for the placement control field: 


AL.VBN=1 Set if block specified is a VBN; otherwise, the 
block is the LBN 

AL. APX=2 Set if you want approximate placement; 
otherwise, placement is exact 

AL.LBN=4 Set if you want starting and ending LBN information 


C.3 BLOCK LOCKING 


Block locking only occurs when the user accesses a file with AC.LKL 
and AC.EXL set in the access control byte of the parameter list. Any 
read or write operation causes a check to see if the block is locked. 


A write access locks a block for exclusive access. A write operation 
can only access a block that is not locked by any accessor. The only 
exception to this is an exact match with a previous lock owned by the 
same accessor. 


A read access locks a block for shared access. A read operation can 
access any block locked for shared access. 


The user must unlock a block with an explicit unlock request, I0.ULK. 
IO.ULK may be used to unlock one or all blocks. 


If all accessors to a file have not requested block locking, the ACP 
returns an error (see Table C-2). 


When the file is deaccessed, all locks owned by the accessor are 
released. 


Each active lock requires eight bytes from the dynamic storage region. 
This storage is deallocated when the file is deaccessed. 


C.4 SUMMARY OF F11ACP FUNCTIONS 


The following is a summary of the functions implemented in FI11ACP. A 
list of accepted parameters follows each function. Aii parameters are 
required unless specified as optional. Parameters other than those 
listed are illegal for that function and must be 0. 
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IO.CRE Create file 


I0.DEL 


IO.ACR 


IO.ACW 


IO.ACE 


IO.DAC 


IO.EXT 


IO.RAT 


IO.FNA 


TO.RNA 


#1 


#2 


#3 


#5 


#1 
#3 


#1 
#2 


#5 


#1 
#2 
#5 


#1 
#2 
# 3 


#1 
#2 


& 


& 


& 


#4 


#4 


#4 


The file identifier block is filled in with the file 
identifier and sequence number of the created file. 


Write Attribute and/or Placement Control List 
(optional) 


Extend Control (optional) 

The amount allocated to the file is returned in the 
high byte of IOST(1) plus IOST(2). 

May be nonzero but must be disabled 

Delete or truncate file 

Optional if the file is accessed 

Size to truncate the file to. If not enabled, the 
file is deleted. If enabled, the remaining 31 bits 
specify the size the file is to be after truncation. 
The change in file allocation is returned in the high 
byte of IOST(1) plus IOST(2). This amount will be 
zero or negative. 

Access file for read only 

Access file for read/write 

Access file for read/write/extend 

File identifier pointer 

Read attributes control (optional) 

Access control must be enabled 

Deaccess file 

File identifier pointer (optional) 

Write attributes control list 

May be nonzero but must be disabled 

Extend file 

Optional if file is accessed 

Placement control attribute list (optional) 

Extend control 

The amount allocated to the file is returned in the 
high byte of IOST(1) plus IOST(2). 

Read attributes 

Optional if file is accessed 

Read attributes control list 


Find name in directory 


Remove name from directory 


) 
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IO.ENA Enter name in directory 
#5 May be nonzero but must be disabled 
#6 File name block pointer 
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IO.ULK Unlock block 
#2 0 or count of blocks to unlock 


#4 & #5 Starting VBN to unlock or 0 to unlock all blocks. 


I0.RVB Read virtual block 
IO.WVB Write virtual block 
#1 User buffer 
#2 Buffer length 

#4 & #5 VBN 


C.5 SUMMARY OF MTAACP FUNCTIONS 


The following is a summary of the functions implemented in MTAACP. A 
list of accepted parameters follows each function. All parameters are 
required unless specified as optional. Parameters other than those 
listed are illegal for that function and must be 0. 


IO.FNA Find file by name 


#5 AC.RWD set in the access control byte indicates 
that the volume is to be rewound prior to the 
search. 

#6 Pointer to file name block. 


The following fields are used as input: 
N.FNAM 
N.FTYP 
N.FVER 
N.STAT 
The following fields are returned by MTAACP: 
N.FID 
N.FNAM 
N.FTYP 
N.FVER 
N.STAT 
IO.ENA Enter name in directory -- a no-op for magnetic tape 
IO.ACR Access for read only 


#1 File identifier pointer. Used to position a 
tape by file identifier. 


#2 Read attribute list (optional) 
#5 Ignored 
IO.ACW Access for read/write 


This function will be rejected with the error 
code IE.PRI. (Extend access is required.) 


IO.ACE 


#1 


#2 
#5 
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Access for read/write/extend 


File identifier pointer. Used to position tape 
by file identifier. 


Read attribute list (optional) 


AC.UPD (update mode). If AC.UPD is set, the 
tape will be positioned to overwrite the file 
and all files beyond the current file will be 
lost. If AC.UPD is not set, the tape will be 
positioned for append. If the file is not’ the 
last file, MTAACP returns the error code 
IE.1ISQ. 


IO.DAC Deaccess file 


#1 
#5 


IO.RVB 
#1 
#2 


#4 
#5 


File identifier pointer is ignored. 


AC.RWD set indicates that the volume iS to be 
rewound after the file is closed. 


Read virtual block 


Buffer address 

Buffer size. The buffer size must be greater 
than 18 bytes and less than the declared block 
length for the entire file. 

High VBN 


Low VBN 


The virtual block number must be either zero or exactly one 
greater than the previous block number. 


IO.CRE Create File 


#1 


#2 


#5 


#6 


File identifier pointer. The file sequence and 
section number will be returned to the user's 
file identifer block. 


Attribute list pointer. Used to write the 
attributes for the newly created file. 
Attribute type code must be positive. 


If AC.RWD is set, the volume will be positioned 
at the beginning and will overwrite the first 
file. This effectively reinitializes the 
volume. 


If AC.RWD is not set and AC.POS is set, the 
volume set will be positioned to the next file 
position beyond the current file and will 
overwrite that file. All files beyond that on 
the volume will be destroyed. 


If neither AC.RWD nor AC.PCOS is set, the volume 
set will be positioned at its end and the new 


file will be appended te the set. 


For unlabeled tapes, MTAACP only checks AC.RWD. 


Filename block pointer. 
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IO.RAT Read Attributes 


#1 File identifier pointer. Used to position the 
tape by the file identifier. 


#2 Attribute list pointer (see Section C.1.2) 
The following attribute list entries are 
meaningful for magnetic tape: 


UIC 
UIC and protection 
UIC, protection, and characteristics 
Protection 
Protection and characteristics 
Characteristics 
2 User file attributes 
File name 
File name and type 
0 File name and type 
File type 
File type and version number 
Version number 
Expiration date 
~9,10 Statistics block (read only) 
-10,0 Entire header (read only) 
y be le Block size 
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IO.APC ACP Control 


#3 One of the following user control function 
codes: 
1 Rewind volume set. 
2 Position to end of volume set. 
3 Close current volume and continue 


processing the next section of the same 
file on the next volume of the volume 
set. 

4 Space physical records in currently 
accessed file. 

5 Get ACP characteristics. 

6 Rewind current file. 


IO.APV Privileged ACP Control 


This function is used only by the MOUNT and DISMOUNT 
commands. This interface is subject to change and, 
therefore, will not be documented until ae future 
release. 


C.6 HOW TO USE THE ACP QIOS 


Although the 


performed by 


operations described in this appendix are normally 


the file-access methods (RMS and FCS), your application 


may issue the ACP QIOs. The required parameters for each QIO are 
described above. The necessary steps for common operations are 
described below. 


NOTE 


The file identifier is the only way to 
refer to a file. 
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C.6.1 Creating a File 
To create a file: 
e Use IO.CRE to create it. 


e Enter it in the Master File Directory (MFD) or a_euser 
directory with IO.ENA. 


C.6.2 Opening a File 
To open a file: 


e Use IO.FNA to find the File Identifier of the directory in the 
MFD. 


e Use IO.FNA to find the File Identifier of the file in the 
directory. 


e Access the file with IO.ACR, IO.ACW, or IO.ACE. 


C.6.3 Closing a File 
To cliose a fiie: 


e Deaccess the file with IO.DAC. 


C.6.4 Extending a File 
To extend a file: 


e Use IO.FNA to find the file identifier if the file is not 
accessed. 


e Use IO.EXT to extend the file. 


C.6.5 Deleting a File 

To delete a file: 
e Use IO.FNA to find the file identifier. 
e Use IO.RNA to remove the directory name. 


e Use IO.DEL to delete the file. 


C.7 ERRORS RETURNED BY THE FILE PROCESSORS 


The error codes returned by FLIiACP and MTAACP are shown in Tabie C-2. 
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Table C-2 
File Processor Error Codes 


IE.ABO | IO.RVB/IO.WVB 


IE.ALC | Extend or create operation 
IE.ALN | An attempt to access a file 


IE.BAD | Any function 


IE.BDR | Directory operations 


| 
IE.BHD | Any operation 


IE.BVR | Directory operations 


Indicates that all 
requested data was not 
transferred by the 
device. 


Indicates that the 
operation failed to 
allocate the file based 
on placement control or 
because of other related 
problems. 


Indicates that a file is 
already accessed on that 
LUN. 


Indicates that a required 
parameter is missing, 
that a parameter that 
must not be present is 
present, that a parameter 
that must be disabled is 
enabled, or that a 
Parameter value is 
invalid. 


Indicates that you 
attempted a directory 
operation on a file that 
is not a directory, or 
that the specified 
directory is corrupted. 
This is usually caused by 
a 0 version number field. 


Indicates that a corrupt 
file header was 
encountered, or that the 
operation required a 
feature not supported by 
the FCP (such as 
multiheader support or 
Support for unimplemented 
features). 


Indicates that you 
attempted to enter a name 
in a directory with a 
negative or 0 version 
number. 


(continued on next page) 


QIO INTERFACE TO THE ACPS 


Table C-2 (Cont.) 
File Processor Error Codes 


Error 
Code Operations Explanation 
IE.BYT | Any function This error is returned if 


the buffer specified is 
on an odd byte boundary 
or is not a multiple of 
four bytes. 
IE.BTP | Unlabeled Magtape Create An attempt was made to 
create an unlabeled tape 
file with a record type 
other than fixed, 


Indicates that the 
checksum of a file header 
is incorrect. 


IE.CKS | Any operation 


IE.CLO | File access operations Indicates that the file 
was locked against access 
by the "deaccess lock 


Indicates that there is 
insufficient free disk 
space for the requested 
allocation. 


IE.DFU | An allocation request 


IE.DUP | An enter name operation Indicates that the name 
and version already 
| | exist. 
| 

IE.EOF | IO.RVB/IO.WVB/I0.DEL | On read operations, this 
indicates an attempt to 
read beyond end of file. 
On truncate operations, 
it indicates an attempt 
to truncate a file to a 
length longer than that 
allocated or that the 

| 

| 

| 


file was already at EOF. 


| 
} 

IE.HFU | An extended operation Indicates that the file 
header is full and cannot 
contain any more 
retrieval pointers and 
that adding an extension 
header is not allowed. 
When this is returned on 
a create operation, it 
indicates that the index 
file could not be 
extended to allow a file 

| header to be allocated. | 
| 


IE.IFC |; Returned by exec 


(continued on next page) 


QIO INTERFACE TO THE ACPS 


Table C-2 (Cont.) 
File Processor Error Codes 


Operations Explanation 


IE.IFU | Create or extend operation Indicates that there are 
no file headers available 
based on the parameters 
specified when the volume 
was initialized. 
Returned on file access, | Indicates that the file 
directory operations, and 
on truncate | 


is already accessed by a 
writer and that shared 
write has not been 
requested or is not 


a file ID has not been supplied and 
that the file is not 
accessed on the LUN. 
IE.NOD | All file operations Indicates that an I/0 
that require DSR request failed due to 
TE.UPN, that the FCP was 
unable to allocate 
required space from DSR 
| or from secondary pool 
for data structures. 


All file operations ' Indicates that the 

| specified directory entry 
does not exist, that a 
file corresponding to the 
file ID does not exist, 
or that the file is 
marked for delete. 


IE.OFL 


allowed. 
IE.LUN | Any operation requiring Indicates that file ID 
Returned by exec The device is off line. 

IE.PRI | Any operation Indicates that the user 
does not have the 
required privilege for 
the requested operation, 
or that the user has not 
requested the proper 
access to the file if the 
file is already accessed 
(for example, an attempt 
to write to a file that 
is accessed for read). 
This also indicates an 
attempt to do file I/0 to 
a device that is not 
ee 


a ee tea on next page) 


IE.RER 


ITE.SNC 


IE.SPC 


TE.SQC 


ITE.WAT 


IE.WER 


| 
| 


IE.WLK 


QIO INTERFACE TO THE 


Table C-2 


File Processor Error 


Operations 


Any operation 


Any operation 


Returned by exec 


Any operation 


File access operations 


Write attributes 
and deaccess 


Any operation 


Any operation 
requiring write access 


Cc 
YY 


on 


ACPS 


(Cont. ) 


Codes 


Explanation 


Indicates that the FCP 
encountered a fatal 
device read error during 
an operation; the 
operation has been 
aborted. 


Indicates that the file 
number and the value 

| contained in the header | 
do not agree. This 
generally means that the 
header has gone bad due 

to a crash or a hardware 
error. 


Indicates an illegal 
buffer. 


sequence number does not 
agree with the file 

header; 
indicates that the file 


usually 


has been deleted and the 
header has been reused. 


is already write accessed 
and lock against writers 


Indicates that the file 
is requested. 


Indicates that the FCP 
encountered an invalid 
attribute. 


Indicates that the FCP 
encountered a fatal 
device write error during 
an operation. The 
operation has been 
aborted but the disk 
Structure.may have been 
corrupted. 


Indicates that the file 
| 
| 
| 


Indicates that the volume 
is software write-locked. 


A/D converter, 14-1 


AFCll, 14-1 

deyvyice-specific 910, 14-2 to 
14-3 

FORTRAN interface, 14-3 to 
14-7 


Standard QIO, 14-2 
status return, 14-8 to 14-9 
A/D gain range, 14-10 
AA11-K, 22-2 
AAV11-K, 22-2 
ACP 
QIO interface, C-l 
ADO1~-D, 14-1 
AD11-K, 22-2 
ADV11-K, 22-2 
AFCll, 14-1 
AM11-K, 22-2 
Analog-to-digital converter 
See A/D converter 
Ancillary Control Processor 
See ACP 
AR11, 16-1 to 16-2 
ASR-33, 2-3, 3~2 
ASR-35, 2-3, 3-2 
Assign LUN 
AST 
service routine, 1-1ll, 1-13 
terminating service, 1-24 
unsolicited-input-character, 
3-32 to 3-33 
ASTXSS, 1-24 
Asynchronous serial line 
interface 
DL11, 2-40, 3-30 
DLI1-E, 12-2 
Asynchronous serial line 
multiplexer 
DH11, 2-40, 3-29 
DHV11, 2-40 
DJ11, 2-40, 3-30 
DZ11, 2-40, 3-30 
Asynchronous System Trap 
See AST 
Auto-baud speed detection, 2-42 


Automatic carriage return, 2-34, 


3-27 to 3-28 


Badge reader, 2-4A, 3-3 
Block size 

magnetic tape, 8-14 
Break-through write, 2-22 
Buffer 

type-ahead, 2-37 


Buffering 
variable-length, 3-28 


Card input error 
error recovery, 11-3 
Card reader, 11-1 
binary format, 11-9 
control character, 11-8 
data format, 11-9 
data format translation, 11-9 
device-specific QIO, 11-3 
format translation, 11-10 
indicator light 
list of, 11-5 to 11-6 
standard QIO, 11-2 
switch 
list of, 11-5 to 11-6 
Card reader check 
recovery, 11-4 
Carriage return 
automatic, 2-34, 3-27 to 3-28 
Cassette, 9-1 
block length, 9-8 
device-specific QIO, 9-3 
space functions, 9-7 
standard QIO, 9~2 
status return, 9-3 to 9-5 
structure, 9-6 
Character 
control, 2-27, 2-33 
task-buffering of received, 
2-36 
vertical format control, 2-34, 
10-6 
Checkpointing 
during terminal input, 3-31 
Control character 
card reader, 11-8 
list of, 11-9 
terminal, 2-27, 2-33, 3-20, 
3-25 
Controller 
DECtape, 6-1 
disk 
UDASO, 5-4 
Counter 
initial value, 18-23 to 18-24 
interrupt 
disconnect, 18-23 to 18-24 
CR1ll1, 11-1 
CTRL/C, 3-20 
CTRL/I, 3-20 
CTRL/J, 3-20 
CTRL/K, 3-20 
CTRL/L, 3-20 


Index-1l 


INDEX 


CTRL/M, 
CTRL/O, 
CTRL/Q, 
CTRL/R, 
CTRL/S, 
CTRL/U, 3-21 

CTRL/Z, 3-21 

Cursor control, 2-39, 


3-20 
2-13, 
3-21 
3-21 
3-21 


3-21 


3-33 


Data format 
card reader, 
DECprinter, 2-4 
LA180, 10-2 

DECtape, 6-1 
device-specific QIO, 6-3 
recovery procedure, 6-6 
reversing direction, 6-7 
select recovery, 6-7 
standard QIO, 6-2 
status return, 6-4 to 6-6 

DECTAPE II 
See TU58 

Density selection 
magnetic tape, 8-15 

Device 
attaching to, 1-26 
detaching, 1-27 
logical, 1-18 
null, 19-1 

Device name 
physical, 1-18 to 1-20 

DH11, 2-40, 3-29 
remote, 3-31 

Diagnostic function 
user-mode, 1-30 

Dial-up line, 2-42 

Digital output 
bistable 

multipoint, 18-18 
multipoint, 18-17 

DIR$ macro, 1-16 

Directive Parameter Block 
See DPB 

Disk 
cartridge 

RKOS, 5-3 
RKO6, 5-3 
RKO7, 5-3 
RLO2, 5-3 
emulator 
ML-1l, 
fixed 
RA80, 5-4 
RA81, 5-4 
RD5l1, 5-4A 
fixed-head 
RF11/RS11, 
RSO3, 5-1 
RSO4, 5-1 
fixed/removable 
RC25, 5-4A 
flexible 
RXOl, 


Li=9 


5-4 


5-1 


5-4 


Disk 
flexible (Cont.) 
RX02, 5-4 
RX50, 5-4A 
geometry, 5-2 
last-track, 5-12 
pack 
RA60, 
RMO2, 
RMO3, 
RMOS, 
RM80, 
RPO2, 
RPO3, 
RPO4, 
RPO5, 
RPO6, 5- 
power-fail recovery, 1-39 
removable/ fixed 
RC25, 5-4A 
status return, 
Disk controller 
UDA5O, 5-4 
DJ11, 2-40, 3-30 
DL11, 2-40, 3-30 
receiver interrupt enable, 
3-33 
12-3 


!t'btet to tet 
WWWHEH WW WW 


Monn owmn vi vm 


5-8 to 5-11 


DMC11, 

DP11l, 12-3 

DPB, 1-13 
diagnostic, 1-31 
previously defined, 
QIO, 1-14 

DQ11, 12-3 

DR11-K, 22-2 

DRV11, 22-2 

DSS/DRS 
configuration, 18-7 

DSS11, 18-1 
address assignment, 

DTO7, 23-1 
device-specifec QI0, 

23-6 

FORTRAN interface, 23-8 
power-fail recovery, 23-6 
standard QIO, 23-2 to 23-3 
status return, 23-7 


1-16 


18-2 


23-4 to 


DU11, 12-3 

DUP11, 12-4 

DZ11, 2-40, 3-30 
remote, 3-31 to 3-32 


End-of-tape 

logical, 9-8 

paper tape, 17-5 
End-of-volume status 

Magnetic tape, 8-15 to 8-16 
Escape code 

conversion, 2-40A, 3-30 
Escape sequence, 2-29, 3-22 

receiving, 2-32 

syntax exception, 2-33, 3-26 

syntax violation, 2-32, 3-24 


Escape sequence (Cont.) 
VT100, 2-31 
Event 
significant, 1-12 
Event flag 
wait for, 1-24 


Fixed and removable, single 
spindle disk, 5-4A 
Format control 
vertical 
line printer, 10-5 to 10-6 
terminal, 3-26 to 3-27 


Gain 
A/D, 14-10 
Get Multiple Characteristics, 
2-13 

A/D converter, 14-2 

card reader, 11-1 to 11-2 

cassette, 9-1 to 9-2 

DECtape, 6-1 to 6-2 

disk, 5-4A 

DTO7 UNIBUS switch, 23-2 

full-duplex terminal driver, 
2-6 to 2-7 

graphic display driver, 20-1 

half-duplex terminal driver, 
3-4 to 3-5 

ICS/ICR, 18-8 

laboratory peripheral system, 
16-2 

line printer, 10-2 to 10-3 

LPA11-K, 21-2 

magnetic tape, 8-3 

message-oriented 
communication device, 


12-4 

paper tape, 17-1 

PCL, 13-2 

table of bits returned, 1-22 
to 1-23 

TU58, 7-1 to 7-2 

UDC1l1, 15-3 


virtual terminal, 4-1 
Graphic display driver 

device-specific QIO, 20-2 

Standard QIO, 20-2 

status return, 20-3 


Hard receive error 
detection, 2-36 


I/O 

canceling request, 1-27 
completion, 1-32 
function code 

Summary, B-l 
issuing request, 1-16 
logical, 1-2 
physical, 1-2 


INDEX 


I/O (Cont.) 
Standard function, 1-25 to 
1-26 
Status block, 1-1ll, 1-35 
status code, 1-33 
summary, B-l 
status condition 
table, 1-36 to 1-38 
virtual, 1-2 
I/O status block 
K-series, 22-32 
LPA11-K, 21-30 to 21-32 
ICS/ICR; 18-1 
address assignment, 18-2 
configuration, 18-7 
device-specific QIO, 18-8 to 
18-12 
direct access, 18-75 to 18-80 
error recovery, 18-71 
FORTRAN interface, 18-35 to 
18-70 
list of supported module, 
18-3 
standard QIO, 18-8 to 18-12 
Industrial control subsystem, 
18-1 
Interface 
terminal, 3-2 
Interrupt 
counter 
disconnect, 18-23 to 18-24 
link task to, 18-27 
digital 
connect, 18-20 to 18-21 
disconnect, 18-21 to 18-23 
link task to, 18-26 
error 
link task to, 18-28 
terminal 
connect, 18-24 
link task to, 18-28 
unsolicited 
activating task, 18-25 
ICS/ICR processing, 18-18 
to 18-20 


K-series, 22-1 
buffer management, 22-32 
FORTRAN interface, 22-7 to 
22-30 
I/O status block, 22-32 
MACRO-11 interface, 22-31 
routine 
generating, 22-4 to 22-5 
Key 
escape, 3-22 
return, 3-22 
rubout, 3=22, 3=24 
special, 2-29 
KSR-33, 2-3, 3-2 
KSR-35, 2-3, 3-2 
KW11-K, 22-3 
KWV11-A, 22-3 


Index-3 


LA100, 2-3 
LA12, 2-3 
LA120, 2-4, 3-3 
LA180, 10-2 
LA180S, 2-4, 3-3 
LA30, 2-4, 3-2 
LA30-P, 3-29 
LA34, 2-4 
LA36, 2-4, 3-2 
LA38, 2-4 
LASO, 2-4A 
Laboratory peripheral 
K-series support routine, 
22-1 
Laboratory Peripheral 
Accelerator 
See LPA11-K 
Laboratory peripheral system, 
16-1 
clock rate, 16-33 to 16-34 
device-specific QI0O, 16-3 to 
16-9 
FORTRAN interface, 16-9 
subroutine summary, 16-11 
to 16-28 
synchronous subroutine, 
16-10 
sampling rate, 16-33 to 16-34 
standard QIO, 16-2 
Status return, 16-29 to 16-33 
Laser printer 
LNO1, 10-2 
Letter-Quality Printer, 2-4 
Line 
remote, 2-41 to 2-42, 3-31 to 
3-32 
Line printer 
list of, 10-1 
LP1l, 10-2 
LS11, 10-2 
LV11, 10-2 
ready recovery, 10-5 © 
status return, 10-4 to 10-5 
LNO1, 10-2 
Logical block 
reading, 1-28 
writing, 1-29 
Logical device, 1-18 
Logical end-of-tape, 9-8 
Logical I/O, 1-2 
Logical unit number, 1-6, 1-17 
changing assignment, 1-7 
retrieving, 1-21 
Logical unit table, 1-6 
LPll, 10-2 
LPA11-K, 21-1 
22-bit addressing, 21-36 
buffer management, 21-32 to 


21-33 

device-specific QIO, 21-27 to 
21-29 

FORTRAN interface, 21-2 to 
21-27 


INDEX 


LPAlLI-K (Cont.) 
I/O status block, 21-30 to 
21-32 
microcode, 21-34 to 21-35 
time-out, 21-35 
unloading driver, 21-35 
LPS11, 16-1 to 16-2 
LQPO2, 2-4 
LS11, 10-2 
LV1ll, 10-2 


Magnetic tape, 8-1 
density selection, 8-15 
device-specific QIO, 8-4 to 
8-9 
list of, 8-2 
select recovery, 8-13 
standard QIO, 8-4 
Status return, 8-10 to 8-12 
eMCALL directive, 1-17 
Message traffic 
low, 12-12 
Message-oriented communication 
device-specific QIO, 12-5 to 
12-7 
fulli-duplex, 12-11 
half-duplex, 12-11 
redundancy checking, 12-11 
Standard QIO, 12-5 
Status return, 12-8 to 12-10 
transmission validation, 
12-11 
Message-oriented communication 
driver, 12-1 
ML-11, 5-4 
Modem, 2-42, 3-32 
Multiplexer 
asynchronous serial line, 
2-40, 3-29 to 3-30 
Q BUS, 2-40 


Null device, 19-1 
Overlapped seek, 5-7 


Paper tape 
error conditions, 17-4 
punch, 17-1 
reader, 17-1 
ready recovery, 17-4 
Standard QIO, 17-2 
status return, 17-3 to 17-4 
Parallel Communications Link 
See PCL 
Parallel interface 
DA11-B, 12-2 
PCL 
receiver 
device-specifc QI0, 13-9 to 
13-11 
standard QIO, 13-8 
status return, 13-11 to 
13-12 


Index-4 


PCL (Cont.) 
transmitter 
device-specife QIO, 13-3 to 
13-5 
standard QIO, 
status return, 
PCL11 
See PCL 
PCL11-B, 
Personal 
Physical 
1-20 
Physical I/d, 1-2 
Power-fail recovery, 1-39 
card reader, 11-4 
DMCl1, 12-12 
DTO7, 23-6 
ICS/ICR, 18-72 
line printer, 10-5 
magnetic tape, 8-14 
Print line truncation, 
Printer 
LA180, 10-2 
LNO1, 10-2 
LPll, 10-2 
LS1l1, 10-2 
LV1l, 10-2 
Process control 
asynchronous, 14-3, 15-16 
synchronous, 14-3, 15-16 
Pseudo-device 
name, 1-21 
Punched card, 


13-3 
13-6 to 13-8 


13-1 
Printer, 2-4A 
device name, 1-18 to 


10-7 


Liat 


QIO, 1-16 
$C form, 1-15 
device-independent, C-1l 
device-specific 
A/D converter, 14-2 to 14-3 
card reader, 11-3 
cassette, 9-3 
DECtape, 6-3 
disk, 5-7 to 5-8 
DTO7, 23-4 to 23-6 
graphic display driver, 


ICS/ICR, 18-8 to 18-12 

laboratory peripheral 
system, 16-3 to 16-9 

LPA11-K, 21-27 to 21-29 

magnetic tape, 8-4 to 8-9 

message-oriented 
communication, 
12-7 

PCL receiver, 


12-5 to 


L3=9 to 13-11 


PCL transmitter, 13-3 to 
13-5 

RA80, 5-8 

terminal, 2-8 to 2-10, 3-5 
to 3-6 

TU58, 7-3 to 7-4 

UDC11, 15-3 to 15-9 


virtual terminal, 4-2, 4-5 


INDEX 


QIO (Cont.) 
$ form, 1-14 
function summary, A-1 
macro format, 1-9 
$S form, 1-15 
standard 
A/D converter, 14-2 
card reader, 11-2 
cassette, 9-2 
DECtape, 6-2 
disk, 5-5 to 5-7 
DT07, 23-2 to 23-3 
graphic display driver, 
20-2 
ICS/ICR, 18-8 to 18-12 
laboratory peripheral 
system, 16-2 
line printer, 10-3 
magnetic tape, 8-4 
message-oriented 
communication, 12-5 
paper tape, 17-2 
PCL receiver, 13-8 
PCL transmitter, 13-3 
terminal, 2-7 
TU58, 7-2 to 7-3 
UDC1l1, 15-3 
summary of form, 1-14 
virtual terminal, 4-2 
QIOWS, 1-16 
Queue I/O and Wait 
See QIOWS 
Queue I/O Request 
See QIO 


RA60, 
RA80, 
RA81, 
RC25, 
RD51, 5-4A 
Ready recovery 
card reader, 
paper tape, 
Receive error 
hard, 2-36 
Remote line, 2-41 to 2-42 
answer speed, 2-42 
disconnecting, 2-23 
Removable and fixed, single 
spindle disk, 5-4A 


5-4 
5-4 
5-4 
5-4A 


11-4 
Tin4 


RF11/RS11, 5-1 
RKO5, 5-3 
RKO6, 5-3 
RKO7, 5-3 
RLO2, 5-3 
RMO2, 5-3 
RMO3, 5-3 
RMO5, 5-3 
RM80, 5-3 
RPO3, 5-1 
RPO4, 5-1, 5-3 
RPO5, 5-3 
RPO6, 5-3 
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RSO3, 5-1 
RSO04, 5-1 
RTO2, 2-4A, 3-3 
RTO02-C, 3-3 
control function, 2-40A, 3-30 
RUBOUT, 3-24 
line printer, 10-6 
RX0O1, 5-4 
RX02, 5-4 
RX50, 5-4A 


Seek 
overlapped, 5-7 
Select recovery 
magnetic tape, 8-13 
Significant event, 1-12 
Speed detection 
auto-baud, 2-42 
SST, 1-12 
Status block 
I/O, 1-35 
Status code 
I/O, 1-33, B-l 
Status return 
A/D converter, 14-8 to 14-9 
card reader, 11-3, 11-7 
cassette, 9-3 to 9-5 
DECtape, 6-4 to 6-6 
disk, 5-8 to 5-11 
DTO7, 23-7 
graphic display driver, 20-3 
ICS/ICR, 18-13 to 18-14 
laboratory peripheral system, 
16-29 to 16-33 
line printer, 10-4 to 10-5 
Magnetic tape, 8-10 to 8-12 
message-oriented 
communication, 12-8 to 
12-10 
paper tape, 17-3 to 17-4 
PCL receiver, 13-11 to 13-12 
PCL transmitter, 13-6 to 13-8 
terminal, 2-23 to 2-27 
TU58, 7-4 to 7-5 
UDC, 15-32 to 15-34 
Synchronous line interface 
DMC1l1, 12-3 
DPll, 12-3 
DQ1l1, 12-3 
DU11, 12-3 
DUP11, 12-4 
Synchronous System Trap 
See SST 


TAL1, 9-1 

TC1i-G, 6-1 

Teletype, 2-3, 3-2 

Terminal 
attaching, 2-12 to 2-13 
control character, 2-27 to 

2-29 

desk-top, 2-3 


INDEX 


Terminal (Cont.) 
device-specific QIO, 2-8, 3-5 
to 3-6, 3-8 
escape sequence, 2-29 
escape sequence recognition, 
2-13 
full-duplex, 2-14 
full-duplex operation, 2-38 
graphics, 2-5 
half-duplex, 3-1 
interface, 2-39 
portable, 2-3 
QIO subfunction bit, 2-9 
special key, 2-30 to 2-31 
standard interfaces, 3-2 
Standard QIO function, 2-7 
status return, 2-23 to 2-27 
subfunction, 3-7, 3-9 
subfunction summary, 2-11 
teletype, 2-3 
type, 2-17 
virtual, 4-1 
Terminal characteristics, 2-13 
to 2-15 
setting, 2-21 
side effects, 2-41, 3- 
virtual terminal, 4-6 
Terminal driver 
loadable, 3-33 
virtual, 4-1 
Terminal line truncation, 3-30 
Trap 
system, 1-12 
Truncation 
print line, 10-7 
terminal line, 3-30 
TU58, 7-1 
Type-ahead, 2-37 


32 


UDA5O, 5-4 
uDC, 15-1 
device-specific QIO, 15-3 to 
15-9 
direct access, 15-10 
FORTRAN interface, 15-15 
FORTRAN subroutine summary, 
15-17 to 15-31 
Standard QIO, 15-3 
Status return, 15-32 to 15-34 
UDC11, 15-1, 18-3 
UMDIOS, 1-31 
UNIBUS 
power-fail recovery, 23-6 
UNIBUS switch, 23-1 
Universal digital controller 
see UDC 
Unlabeled tape, 8-15 to 8-16 
User-mode diagnostic function, 
12n 
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Vertical format control 
line printer, 10-5 to 10-6 
terminal, 2-33, 3-26 to 3-27 
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INDEX 


Virtual block VT105, 2-6 
reading, 1-28 VTli, 20-1 
writing, 1-29 VT131, 2-6 

Virtual I/O, 1-2 vVT50, 2-5, 3-3 

Virtual terminal, 4-1 VT50H, 2-5, 3-3 
device-specific QIO, 4-2, 4-5 VT52, 2-5, 3-4 

vs60, 20-1 vVT55, 2-5, 3-4 

VTO5B, 2-5, 3-3 VT61, 2-5, 3-4 

VT100, 2-5, 3-4 
escape sequence format, 2-31 Write 

VT101, 2-6 break-through, 2-22 

VT102, 2-6 WTSES, 1-24 
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RSX-11M/M-PLUS 
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READER’S COMMENTS 


NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the 
company’s discretion. If you require a written reply and are eligible to receive one under Software 
Performance Report (SPR) service, submit your comments on an SPR form. 


Did you find this manual understandable, usable, and well organized? Please make suggestions for improvement. 


Did you find errors in this manual? If so, specify the error and the page number. 


Please indicate the type of user/reader that you most nearly represent. 


[] Assembly language programmer 

(] Higher-level language programmer 

|] Occasional programmer (experienced) 

_] User with little programming experience 
_] Student programmer 

(| Other (please specify) 
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